Impersonation

Endpoints for admin users to impersonate other users for support and troubleshooting.

POST /api/_impersonate

Impersonate another user, creating a child session.

Authentication: Required (must be superuser)

Permission:

• Root session user must be a superuser
• Cross-tenant impersonation requires manager tenant superuser AND crossTenantAccess enabled on target tenant

Request Body:

Field	Type	Required	Description
username	string	Yes	Username to impersonate
tenant	string	No	Target tenant (defaults to current tenant)

Example Request (Same Tenant):

{
  "username": "testuser"
}

Example Request (Cross-Tenant):

{
  "username": "admin",
  "tenant": "customer-tenant"
}

Pre-blocks:

• Request session lookup
• Related sessions lookup (parent and children)
• Root session identification
• Permission check (superuser, cross-tenant rules)
• Target user validation
• Session creation or reuse
• Credentials generation
• WebSocket token generation

Response:

{
  "id": "child-session-id",
  "tenant": "acme",
  "username": "testuser",
  "parent": "admin-session-id",
  "user": {
    "username": "testuser",
    "displayName": "Test User"
  },
  "createdAt": "2024-02-09T10:00:00Z",
  "expiresAt": "2024-02-09T18:00:00Z",
  "wsToken": "ws-token-for-impersonated-session",
  "_links": {
    "self": { "href": "/api/sessions/child-session-id" },
    "inf:user": { "href": "/api/users/testuser" }
  }
}

Cookie Behavior:

Sets the session cookie (sid) to the new impersonated session ID.

---

Impersonation Rules

Permission Requirements

Root Session	Target Tenant	Allowed?
Manager superuser	Any tenant with crossTenantAccess: true	Yes
Manager superuser	Any tenant with crossTenantAccess: false	No
Manager non-superuser	Any tenant	No
Non-manager superuser	Same tenant	Yes
Non-manager superuser	Different tenant	No
Non-manager non-superuser	Any tenant	No

Root Session Concept

The root session is the original authenticated session (no parent field). Impersonation permissions are always evaluated based on the root session user, not the currently impersonated user.

This prevents privilege escalation where:

1. Admin impersonates User A
2. User A is not an admin
3. While impersonated as User A, cannot further impersonate User B

Session Hierarchy

Root Session (admin@manager)
├── Child Session 1 (user1@acme)
├── Child Session 2 (user2@acme)
└── Child Session 3 (admin@beta)

All impersonation sessions created from the same root session are tracked as "related sessions" and can be listed via GET /api/my-sessions.

---

Session Reuse

If an existing impersonated session already exists for the target tenant and username within the related sessions, that session is reused instead of creating a new one.

Benefits:

• Maintains continuity when switching between impersonated users
• Preserves session state and data
• Reduces session table bloat

---

Exiting Impersonation

Option 1: Logout (Restore Parent)

POST /api/logout

When logging out of an impersonated session (one with a parent), the session cookie is set to the parent session ID instead of being cleared.

Result: Returns to the original admin session

Option 2: Switch to Another User

POST /api/_impersonate
{ "username": "another-user" }

Directly switch from one impersonated user to another.

Option 3: Delete Child Sessions

DELETE /api/sessions/{rootSessionId}/children

Terminate all impersonated sessions and return to root.

---

Cross-Tenant Impersonation

Requirements

1. Root session user must be manager tenant superuser
2. Root session user must have superuser: true
3. Target tenant must have crossTenantAccess: true

Example Scenario

Setup:

• Manager tenant has user admin@manager with superuser: true
• Customer tenant acme has crossTenantAccess: true
• Customer tenant has user user1@acme

Flow:

1. Login as admin@manager
2. Impersonate user1@acme:

   POST /api/_impersonate
   {
     "username": "user1",
     "tenant": "acme"
   }

3. Session is created with:
   • tenant: "acme"
   • username: "user1"
   • parent: admin-session-id

Cross-Tenant Lockout

If a target tenant has crossTenantAccess: false, impersonation attempts will fail with 403 Forbidden, even for manager superusers.

---

Use Cases

Support and Troubleshooting

• Reproduce issues reported by users
• Verify permission configurations
• Debug UI or workflow problems
• Test user-specific settings

Testing

• Test multi-user workflows
• Validate role-based access controls
• Verify team memberships and permissions

Training and Demos

• Demonstrate features from different user perspectives
• Show role-specific functionality
• Create training scenarios

---

Security Considerations

Audit Logging

All impersonation actions should be logged:

• Who impersonated whom
• When the impersonation occurred
• Which tenant was accessed

Permission Checks

Impersonation permission is checked at the root session level, not the current session. This prevents:

• Privilege escalation
• Unauthorized cross-tenant access
• Impersonating users with higher privileges

Session Expiration

Impersonated sessions have their own expiration times based on the tenant's sessionExpireMinutes setting.

Best Practices

• Limit Duration - Only impersonate as long as necessary
• Document Reason - Log why impersonation was needed
• Single Purpose - Exit impersonation after completing the task
• Audit Access - Review impersonation logs regularly

Security Alert

Impersonation grants full access to the target user's data and permissions. Use responsibly and only when necessary for support or troubleshooting.

Activity Logging

A future enhancement may include creating an Activity record when a user account is impersonated, making it visible in admin feeds.