Skip to main content

0016: User Impersonation (User Switcher) Strategy

Date: 2025-08-11

Status: Superseded by ADR-0017: Multiple Account Management Strategy

Context​

This ADR initially used the term "User Switcher" to describe what was thought to be a requirement for administrative user impersonation (i.e., a support agent acting "as" another user for troubleshooting).

Further clarification revealed that the primary user story was not for administrative impersonation, but for an end-user to conveniently switch between their own multiple, distinct accounts (e.g., a personal account and a work account) within the same browser session, similar to Google's or Microsoft's account switching functionality.

These are two fundamentally different features:

  1. User Impersonation: An admin acting on behalf of another user.
  2. Multiple Account Management: An end-user switching between their own accounts.

This ADR, which describes the impersonation flow, was therefore superseded by ADR-0017, which correctly defines the strategy for multiple account management. The concept of switching between a user's different tenant contexts (e.g., from a global view to a tenant-specific view) is a separate concern, addressed in ADR-0025.

Decision​

We will implement user impersonation as a formal, backend-driven flow within the iam-service.

  1. Permissions: A new permission, user:impersonate, will be introduced. Only users with this permission can initiate an impersonation session.
  2. API Endpoint: A new endpoint, POST /api/v1/iam/impersonate, will be added to the iam-service. This endpoint will accept a target_user_id.
  3. Backend Validation: The iam-service will verify that the currently authenticated user has the user:impersonate permission and perform any additional business logic checks (e.g., an admin from one tenant cannot impersonate a user from another).
  4. Impersonation Token: If validation passes, the iam-service will provide an enriched token for the target user. This token will contain the standard claims of the target user (sub, name, etc.) but will also contain an act (actor) claim (as per RFC 8693) which identifies the original administrative user. The iam-service does not issue OIDC tokens; it enriches claims based on the upstream IdP's token.
  5. Frontend Flow: The shell-app will call the /impersonate endpoint. On success, it will receive the new tokens, replace its current tokens in storage, and trigger a full session reload.
  6. Audit Trail: The iam-service must emit a UserImpersonationStarted domain event containing the original user ID, target user ID, and tenant ID for a non-repudiable audit log.
  7. Ending Impersonation: The UI will provide a clear visual indicator that an impersonation session is active. This banner will contain a "Stop Impersonating" button, which will log the user out, requiring them to log back in as their original self.

Consequences​

Positive​

  • Secure: The flow is controlled and validated by the backend, not the client.
  • Auditable: The act claim and the domain event provide a clear audit trail.
  • Standard-Compliant: Uses the act claim, a standard approach for delegation/impersonation.

Negative​

  • Increased Complexity: This is a significant feature that adds complexity to both the iam-service and the shell-app.
  • Full Reload Required: The frontend must perform a full session reload to use the new tokens, which is a more disruptive user experience than a simple dropdown. This is a necessary trade-off for security.