← Back to Core Domains

4.9 Impersonation Mode

Impersonation lets a tenant super user temporarily use another member’s effective identity for support and troubleshooting. It is tenant-local, visibly indicated, mutually exclusive, and audited.

Flow

MembersController::impersonate() verifies that the current member is a super user, rejects self-impersonation and nested sessions, loads the target from the active tenant, and calls ImpersonationService::start(). stopImpersonating() restores the original administrator and clears identity caches.

The session snapshot records both identities. While active, policy checks use the impersonated member’s permissions. The global layout displays the impersonation state and a way to stop it.

Audit trail

• ImpersonationSessionLogs records start and stop events.
• BaseTable records saves and deletes in ImpersonationActionLogs, including both identities and request/record metadata.
• Logging failures are warnings worth investigating; do not intentionally bypass the base-table hooks.

Tables that do not extend BaseTable need an explicit security review before they are used for impersonated writes.

Security rules

• Keep start/stop actions state-changing and CSRF-protected.
• Never allow impersonation across tenant contexts or from the platform administration identity.
• Do not expose or mutate the session payload from client input.
• Do not suppress the visual banner or original-administrator recovery path.
• Audit access to sensitive records even when the impersonated member is authorized.

Verification

Cover super-user-only activation, self/nested rejection, effective policy changes, cache clearing, start/stop logs, write/delete logs, the persistent banner and keyboard-accessible stop control, logout/session expiry, and isolation between two tenant hosts.