Impersonation Overview
User impersonation allows authorized administrators to assume the identity of another user for troubleshooting, support, and debugging purposes. The feature is designed with strict security controls and comprehensive audit logging to maintain compliance and prevent misuse.
How Impersonation Works
When an admin starts an impersonation session, the system generates a scoped token that grants the admin the same permissions as the target user. The admin can then make API calls and access the platform as if they were the target user.
Admin ImpersonationService TokenService
| | |
|--- Start (target, reason)->| |
| |--- Validate permissions--|
| |--- Check constraints ----|
| |--- Create session ------->|
| | |--- Generate scoped token
| |<-- Session info ---------|
|<-- ImpersonationResult----| |
| | |
| (use scoped token for API calls) |
| | |
|--- End session ----------->| |
| |--- Revoke token -------->|
| |--- Record end time ----->|
|<-- 204 No Content --------| |Security Controls
| Control | Description |
|---|---|
| Role requirement | ADMIN role or users:impersonate authority required |
| Protected roles | Cannot impersonate users with PLATFORM_ADMIN role |
| Reason required | A reason of 10-1000 characters must be provided |
| Session limit | Maximum concurrent impersonation sessions enforced |
| Auto-expiry | Sessions expire after a configurable timeout |
| Full audit | All actions during impersonation are logged |
Session Lifecycle
| State | Description |
|---|---|
| Active | Admin is currently impersonating the target user |
| Ended | Admin voluntarily ended the session |
| Expired | Session exceeded the maximum duration |
| Force-ended | Another admin force-terminated the session |
Section Pages
| Page | Description |
|---|---|
| Starting Sessions | How to initiate an impersonation session with required parameters |
| Ending Sessions | Normal termination, force-end, and auto-expiry |
| Audit Trail | Audit logging, compliance reporting, and action recording |