Skip to content

Impersonation

Audience: super_admin operators supporting users inside a tenant.

Scope: How to start, use, stop, and audit LMS impersonation from the admin UI. The technical session contract lives in development/auth.md.

Impersonation lets a super_admin temporarily sign in as another tenant user to reproduce a support issue, verify tenant-scoped data, or confirm a learner/admin experience. It is an audited support tool, not a role-management shortcut. Tenant admins and course admins cannot impersonate users.

Prerequisites

  • Sign in as a super_admin.
  • Browse the target tenant's host before starting. Use the tenant subdomain or custom domain, not the apex marketing host.
  • For cross-tenant support, switch to the target tenant host first. Host resolution is documented in Multi-Tenant Administration.
  • In local development, sign in on http://lvh.me:3001 first, then switch to the tenant subdomain. See Developer Setup And Contributing for the same host pattern used by e2e tests.

Start Impersonation

  1. Open /admin/users on the target tenant host.
  2. Find the target user and open /admin/users/\[id\].
  3. Click Impersonate.
  4. The LMS switches the session to the target user and navigates to /learn/dashboard.

If the button is not present, confirm that you are signed in as super_admin and that you are viewing the target user from the correct tenant host.

What Changes During Impersonation

During impersonation, the active JWT belongs to the target user. The UI, permissions, course access, and learner dashboard match that user's role and tenant.

The LMS also sets the __impersonator_uid HTTP-only cookie with the original super-admin user id. That cookie lets the stop flow restore the original session and expires after four hours.

An amber impersonation banner appears in the admin shell when the impersonated user can access /admin/*. The banner includes Stop impersonation and is the primary way to restore the original session. Learner routes such as /learn/dashboard do not currently show this banner.

Stop Impersonation

The preferred stop path is:

  1. Open /admin while impersonating an admin-capable user.
  2. Confirm the amber impersonation banner is visible.
  3. Click Stop impersonation.
  4. The LMS restores the original super_admin session and returns to /admin.

For learner-only targets, /admin is blocked because the impersonated user has the student role. In that case, sign out and sign back in as the original super-admin account to recover. The clean stop path still requires the admin banner or POST /api/admin/impersonate/stop, so prefer impersonating a tenant_admin when the support task requires admin UI access.

Constraints And Failures

Condition Result
Caller is not super_admin The UI hides Impersonate; direct API calls return 403.
Target user is super_admin Start is refused with 403.
Target user is deactivated Start is refused with DEACTIVATED.
Audit logging fails Start is refused so impersonation cannot proceed without an audit trail.
No active impersonation cookie on stop Stop returns NOT_IMPERSONATING.

Auditing

Both start and stop write audit events:

  • auth.impersonate.start
  • auth.impersonate.stop

Use /admin/audit to filter by action prefix, actor, target user, or tenant. For course-support investigations, the same audit viewer is summarized in Course Administration.

During the impersonated session, user actions run as the target user and should be reviewed alongside the start/stop events when reconstructing a support timeline.

Technical Reference

The implementation reuses the one-time consumed-token credentials path. Start mints a proof for the target user and sets __impersonator_uid; stop signs out the target session, mints a proof for the original super-admin, signs back in, and clears the cookie. See Authentication - Super-Admin Impersonation for the API routes, session mechanics, and consumed-token rationale.