Skip to main content

Impersonation is dual-identity

The property​

When a support engineer impersonates a user, the platform tracks both identities throughout the impersonation window:

  • Actor identity — the real session user (the support engineer)
  • Target identity — the impersonated user

Permission checks run against the impersonated user's permission set. Audit records record both identities on every event.

Why dual-identity​

A SOC 2 audit asks: "who actually did this?" If the answer is "the impersonated user," the trail is wrong — that user did not press the button. If the answer is "the support engineer," the trail is incomplete — the action ran with the impersonated user's permissions, not the support engineer's.

The dual-identity model records the truthful answer: a support engineer named X performed action Y while impersonating user Z. Both identities are present in the audit record, with their roles distinguished.

Why not session-overlay (replace identity during impersonation)​

A simpler model would be: "when impersonating, the session becomes the impersonated user. All checks and audit emits use that identity." The failure mode is that the audit trail loses the support engineer's identity. Investigating a compromise or misuse becomes harder because the only signal that anything unusual happened is the impersonation start/stop record — every action in between looks like the user did it themselves.

Dual-identity keeps the truth on every record, not just the start/stop pair.

Permission semantics​

Permission checks during impersonation use the impersonated user's permission set, not the support engineer's. This is deliberate:

  • An impersonation session cannot grant the support engineer elevated capabilities (no privilege escalation).
  • The impersonation models the user's experience — what they can do, what they can see — for legitimate support purposes.
  • If the support engineer wants to take a platform-level action, they exit impersonation and run it under their own identity.

Bounded duration​

Impersonation sessions have a maximum duration (4 hours per the spec). The bound limits the credential blast radius if a support engineer's session is compromised mid-impersonation. See OpenSpec for the binding contract.

Implementation seam​

  • Impersonation service: libs/api/services-api/src/lib/core/auth/services/ (the impersonation service lives in the auth module)
  • Audit context: libs/api/services-api/src/lib/core/audit/audit-context.factory.ts carries both identities on every emit
  • Spec: openspec/specs/impersonation-service/spec.md

Consequences​

  • Every audit record produced during impersonation carries two identity fields. Queries against the audit collection that filter by "who did this" must decide whether they care about the actor (the support engineer) or the target (the impersonated user) — both are present and both are correct answers to different questions.
  • Permission checks during impersonation use the impersonated user's permission set. A support engineer cannot escalate privileges by entering impersonation. Platform-level actions are not available during an impersonation session; the engineer exits, runs the action under their own identity, and re-enters if needed.
  • The 4-hour duration bound is a credential-blast-radius limit, not a UX hint. Extending it requires a separate compliance + security review — the current bound is the explicit SOC 2 posture under the impersonation spec.
  • Impersonation state lives in Redis-backed session storage. A sticky-session task failover does not lose impersonation state; the dual-identity record format must remain serializable through RedisCacheService operations.
  • The session overlay alternative (replacing identity instead of layering it) is structurally disallowed by this decision. Any future "switch user" feature that wants a session-overlay shape needs a new audit context distinct from the impersonation flow — the impersonation flow's truthfulness depends on never collapsing the two identities.