Support impersonation lets a support engineer act inside a customer's account to reproduce a bug or fix a broken state. If the implementation simply swaps the engineer into the customer's session, actions land under the customer's name with no record of who really took them, and the support tool hands over the same authority as the customer with none of the constraints. This post documents a safe default and its trade-offs.

System description

An impersonation session is a separate, short-lived credential that lets a named support agent act as a specific customer, with both identities recorded on every action. The agent never receives the customer's real session, and high-risk actions stay blocked for the duration.

Architecture choice

There are two common ways to authorize an impersonation: an internal approval, or an explicit customer grant.

Policy-governed access (internal)

The product authorizes impersonation internally. A role policy defines who may impersonate which accounts; sensitive accounts or regulated data can add an explicit approver on top.

Use this when:

  • Support must handle urgent incidents without waiting on the customer

  • The product has no per-customer way to grant access

  • Strong audit and short-lived sessions are an acceptable control on their own for most accounts

Trade-off: the customer is not in the loop at grant time, so the banner and the audit trail carry the trust.

Customer-granted access (consent-based)

The customer enables an impersonation permission, per account or per session, before support can act.

Use this when:

  • Customers expect to control who can enter their account

  • A contract or regulation requires explicit consent

  • The customer has an admin who can toggle the permission

Trade-off: urgent support stalls when no customer admin is available to grant access.

Common middle ground: customer consent for standard accounts, with an internal break-glass path that carries heightened approval and alerting for emergencies.

Golden path

Start with this path:

Request impersonation with a reason → authorize by policy or approver → mint a short-lived act-as session → act behind a visible banner → block high-risk actions → log both identities → expire or end on demand

Related patterns:

Minimal system context

  • Support agent (identity): the internal user who needs to act inside a customer account

  • Customer user (subject): the account the agent acts as

  • Approver (authorization): the policy or person that authorizes a request

  • Impersonation service (control plane): mints and ends impersonation sessions

  • Impersonation session (credential): the short-lived act-as token and its server-side record

  • Action policy (authorization): the rule set that blocks high-risk operations during a session

  • Impersonation banner (indicator): the in-product signal that a session is active

  • Audit log (data plane): the append-only record of every impersonated action with both identities

Core design

Impersonation session

An impersonation session is a distinct credential, not a copy of the customer's session. Model it as delegation, not a swap: the customer is the subject and the support agent is the actor. With JWTs, you carry that split in an act claim, the form described in RFC 8693. A server-side record backs the token:

  • impersonation_id (opaque UUID)

  • actor_principal_id (the support agent)

  • subject_user_id (the customer being acted as)

  • tenant_id (the customer's tenant)

  • reason, ticket_ref, approved_by

  • mode (read_only or read_write)

  • started_at, expires_at, ended_at (the row moves through active → ended | expired once)

Minimal API shape

POST   /admin/impersonations              → 201 { impersonation_id, expires_at }
GET    /admin/impersonations/{id}         → 200 { actor, subject, mode, expires_at, status }
POST   /admin/impersonations/{id}/elevate → 204 (request read_write; needs approval)
DELETE /admin/impersonations/{id}         → 204 (end the session)

Clients never send the actor identity; it comes from the agent's authenticated session. The subject_user_id and the mode come from the grant, not from the request that performs an action. The create call returns an impersonation session id or act-as credential, never the customer's normal access or refresh token.

Threat model

Baseline assumptions

  • Support agents are semi-trusted: authenticated internal users who may act outside policy, by mistake or intent

  • The product derives the acting agent's identity from the agent's own authenticated session, not from the request body

  • The customer's data and account-control actions are higher-value than any single support task

  • Audit logs are append-only and stored apart from general application logs

  • Impersonation runs inside your app, below the customer's identity provider, so the tenant's conditional-access rules (IP allowlists, device posture) do not apply to the support agent

  • Standard infra controls (TLS, admin AuthN, secret management, log hygiene) are assumed to be in place. This model focuses on the impersonation lifecycle itself

A note on risk

This table is not a checklist. Focus on preventing the highest-impact failures first. Detection and response are acceptable where prevention is impractical.

Phase 1: Authorization and start

Focus: Restricting who may impersonate whom, and on what grounds

Asset

Threat

Baseline Controls

Mitigation Options

Risk

Customer account

Unauthorized impersonation: Anyone with admin-panel access can act as any account without a separate grant

Admin-panel role required

1. Gate impersonation behind a dedicated permission, separate from general admin access

2. Scope each agent to the accounts they are assigned, not the whole customer base

3. Govern access with a role policy, and add a second approver for security-sensitive or high-tier accounts

High

Grant integrity

Identity spoofing: The action request sets the actor or subject, so a caller chooses who it acts as or on whose behalf

None

1. Derive the actor from the agent's authenticated session, never the request body

2. Take the subject and mode from the stored grant, not the action request

3. Reject actor and subject fields supplied in the body

Medium

Accountability

Missing reason: A session starts with no recorded purpose, so a later review cannot separate a legitimate session from abuse

None

1. Require a non-empty reason and a ticket reference, validated against the ticketing system where possible

2. Record the reason and ticket on the session at start

3. For sensitive accounts, require and record a second-party approval

Medium

Privileged accounts

Privilege jump: An agent impersonates an org owner or admin to take actions the agent could never authorize directly

None

1. Cap impersonation to target roles at or below the agent's own grant authority

2. Route owner-level impersonation through a separate, heightened-approval path

3. For consent models, require the customer to opt in before admin-tier accounts are impersonable

Medium

Tenant access policy

Conditional-access bypass: Impersonation runs below the customer's IdP, so the session skips the tenant's IP allowlist, device posture, and step-up rules

None

1. Re-evaluate the tenant's IP and device rules against the support agent's context where the product can read them

2. Notify the tenant's security contacts that a session bypassed their access policy

3. Let strict zero-trust tenants disable impersonation and fall back to a screen-share

Medium

Emergency access path

Break-glass abuse: An emergency bypass of consent or approval becomes the routine way to reach sensitive accounts

Audit log

1. Put break-glass behind its own permission and a second approver

2. Require a short TTL, a mandatory ticket, and a post-session review before the session is marked closed

3. Notify security and the customer's admins whenever break-glass starts on a sensitive account

Medium

Support agent session

Stolen support session: An attacker with the agent's session or device opens impersonation sessions across many customers, reading PII and keys without a single write

Admin-panel SSO session

1. Require a fresh step-up (WebAuthn or MFA) at the moment impersonation is requested, not an existing login

2. Bind the grant to that step-up so it cannot be replayed from a stale session

3. Rate-limit and alert on a burst of impersonation starts by one agent

Low

Phase 2: Active session

Focus: Constraining what the session can do and keeping it visible

Asset

Threat

Baseline Controls

Mitigation Options

Risk

Customer data

Sensitive action abuse: During a session the agent changes credentials, exports data, deletes the account, or alters billing

None

1. Deny a defined high-risk set in the impersonation context (credential, MFA, and email changes, data export, deletion, billing, and new API keys or impersonations), and deny any action whose policy decision is unavailable

2. Default the session to read-only; require explicit elevation and a second approval for writes

3. Step-up re-authenticate the agent before any allowed write

Medium

Account oversight

Silent access: The customer has no way to see that support is acting in their account

None

1. Surface active and recent impersonation sessions to the customer's own admins in the product

2. Notify the customer when a session starts, in real time for sensitive accounts or regulated data

Medium

Account integrity

Wrong-account action: The agent forgets a session is live and acts in the customer's account thinking it is their own or a test tenant

None

1. Show the agent a persistent banner naming the impersonated customer and the time remaining

2. Visually distinguish the impersonation view from the agent's normal view

3. Confirm the target account before the first write

Low

Session credential

Becoming the user: The act-as token behaves like a normal customer session or can be exchanged for the customer's refresh token

None

1. Mint a distinct token type with an act claim, recognizable to downstream services as impersonation rather than a normal session

2. Bind the audience to the one subject and tenant, and block exchange for any standard session or refresh token

High

Phase 3: Audit and teardown

Focus: Attributing every action and ending access cleanly

Asset

Threat

Baseline Controls

Mitigation Options

Risk

Audit trail

Audit ambiguity: Impersonated actions are attributed to the customer alone, either in the app's own logs or after the gateway downgrades the act-as token for a downstream service, so an investigation cannot tell who acted

Per-user action logs

1. Write the agent (actor), the customer (subject), the impersonation_id, and the ticket on every action

2. Propagate the act claim to every downstream service and never downgrade it to a plain customer token; reject act-as calls that arrive without it

3. Keep impersonation events in an append-only store separate from general logs, and emit distinct start and end events

Medium

Session lifecycle

Lingering session: The session outlives the support need, or an ended, expired, or revoked session keeps working

TTL expiry

1. Set a short absolute TTL and an idle timeout, and end the session when the linked ticket closes

2. Back the token with a server-side session so revocation stops it on the next request, with no offline-verifiable token outliving the record

3. Give security and the customer's admins a kill switch, and revoke an agent's active sessions when their impersonation permission is removed

Medium

If you use customer-granted access

If the customer grants access instead of an internal policy or approver, the trade-offs shift:

  • A revoked customer permission must end active sessions at once, not only block new ones

  • Consent does not retire the high-risk action policy; a consenting customer still does not expect support to reset their password

  • The audit record must capture the consent grant and its scope alongside each session

  • Emergencies still need a break-glass path, which brings back the internal-approval threats for that path

FAQs

Should impersonation sessions be read-only by default?

Yes. Most support work is reproduce-and-observe, and a read-only default removes the entire write-side abuse class without slowing those tasks. When a fix genuinely needs a write, move the session into a read-write mode that requires a separate approval and a step-up re-authentication, so the risky path is the exception and is logged as one.

Should the customer be notified when support impersonates a user?

At a minimum, the customer's own admins should be able to see active and recent impersonation sessions in the product. For sensitive accounts or regulated data, send a real-time notification when a session starts. Silent impersonation is what turns a support tool into a trust problem, so visibility belongs inside the control, not bolted on later.

Verification checklist

  • Authorization and start

    • Impersonation requires a permission distinct from general admin access; removing it blocks new sessions

    • Starting a session requires a fresh step-up (WebAuthn or MFA), not just an existing login

    • A request without a reason and a ticket reference is rejected

    • Where second-party approval is required, the requester cannot approve their own request

    • An agent cannot impersonate a target whose role outranks the agent's grant authority

  • Session scope and sensitive actions

    • A blocked high-risk operation fails inside an impersonation session (for example, a password reset or a data export)

    • A new session is read-only; writes require explicit elevation and a second approval

    • The act-as token cannot be exchanged for the customer's normal session or refresh token

  • Visibility

    • The customer's admins can see active and recent sessions

    • The customer is notified when a session starts on a sensitive account

    • The agent sees a persistent banner naming the impersonated customer and the time remaining

    • Ending the session from the banner stops access immediately

  • Identity and audit

    • Every impersonated action records both the agent and the customer identity, the impersonation_id, and the ticket

    • Session start and end are distinct audit events

    • Impersonation logs live in an append-only store separate from general logs, restricted to security and compliance

  • Enforcement and propagation

    • If the action policy cannot be evaluated, the action is denied rather than allowed

    • An internal service called during a session records the support agent, not the customer alone

    • A tenant with strict conditional access can disable impersonation entirely

  • Lifecycle and teardown

    • The session expires on a short absolute TTL and on idle timeout

    • A killed or expired session's token stops working on the next request

    • Removing an agent's impersonation permission revokes their active sessions

    • Direct reuse of the act-as token after the session ends fails

Implementation & Review

The full threat model matrix, architectural diagrams, and a printable verification checklist for this pattern are available in the Secure Patterns repository. Use these artifacts to guide your design reviews and internal audits.

Keep Reading

© 2026 Secure Patterns.
beehiivPowered by beehiiv