Appearance
Impersonation
Platform admins with support permissions can sign in as a tenant owner to troubleshoot issues, train users, or verify configuration — without knowing the owner's password.
Requirements
| Requirement | Detail |
|---|---|
| Permission | platform.tenants.impersonate |
| Roles | SuperAdmin, Admin, Support |
| Target | Tenant must have an active owner account |
| Audit | Impersonation codes are short-lived and single-use |
Impersonation flow
mermaid
sequenceDiagram
participant PA as Platform Admin
participant API as EaseLab API
participant TP as Tenant Portal
PA->>API: POST /admin/tenants/{id}/impersonate
API-->>PA: code + portalUrl
PA->>TP: Open /impersonate?code=...
TP->>API: POST /auth/impersonate/exchange
API-->>TP: JWT + refresh cookie
TP-->>PA: Signed in as tenant ownerStep-by-step
1. Start impersonation
From Admin Portal → Tenants → Impersonate, or:
POST /admin/tenants/{tenantId}/impersonateResponse:
| Field | Description |
|---|---|
code | One-time exchange code (2-minute TTL) |
portalUrl | Tenant portal URL with impersonation route |
2. Exchange code
The tenant portal opens /impersonate and calls:
POST /auth/impersonate/exchange
{ "code": "..." }On success, the admin receives a full tenant-owner session (JWT + refresh cookie).
3. Work as tenant owner
The impersonated session has:
- All tenant admin permissions
- Full access to lab data
- Normal tenant portal UI
A banner should indicate impersonation mode (implementation in frontend).
4. End session
Log out normally (POST /auth/logout). Return to the admin portal and sign in with platform credentials.
Security properties
| Property | Value |
|---|---|
| Code TTL | 2 minutes |
| Storage | Redis/distributed cache |
| Reuse | Codes are consumed on exchange |
| Target user | Tenant owner (IsTenantAdmin) |
| Platform admin identity | Stored in impersonation payload for audit |
What impersonation is not
| Scenario | Supported? |
|---|---|
| Impersonate a specific staff user | No — owner only |
| Impersonate without permission | No — 403 |
| Extend code after expiry | No — start new impersonation |
| Impersonate locked tenant (read-only) | Yes — read access works; writes blocked by lock middleware |
Best practices
- Use impersonation only for legitimate support tasks.
- Inform the tenant when accessing their account.
- Do not create invoices, delete data, or change passwords without explicit approval.
- Prefer read-only investigation when possible.
- Enable 2FA on platform admin accounts.