Impersonation in JWTs: act, on_behalf_of, and impersonator claims

How to encode "support engineer is signed in as customer" in a JWT, and what audit log entries you owe regulators when you do.

Last updated: May 2026

shield

Private: Decoding, analysis, signature verification, and token generation all run in your browser. Nothing is sent to any server, except a JWKS URL you explicitly enter and click Verify on.

Paste your JWT

At a glance

RFC standard claim: act (RFC 8693)
Common alternatives: on_behalf_of, impersonator
sub during impersonation: The impersonated user's id (not the staff member's)
Audit requirement: Log both identities + reason + duration

Most B2B SaaS products eventually need a "log in as customer" feature for support — a staff member signs in, picks a customer account, and acts on their behalf. The right way to encode this in a JWT is with an explicit impersonation claim, not by silently switching `sub`. RFC 8693 defines `act` for exactly this case.

Why a dedicated claim, not a switched sub

A naive impersonation implementation has staff "switch" their session: the JWT's `sub` becomes the customer's id, and the staff identity disappears. This is wrong on two levels. First, audit logs lose the actor — there's no record that staff did anything; it looks like the customer themselves did it. Second, authorization gets simpler in the wrong way: any code that gates "only staff can do X" stops triggering, because the token no longer identifies a staff member.

The right pattern keeps both identities visible: the outer `sub` is the customer (so authorization scoping uses the customer's tenant context, as it should), and a separate `act` claim records the staff actor. Audit log middleware captures both.

Frequently asked questions

What does the act claim look like?expand_more

It's a nested object identifying the actor (the person doing the impersonating). Example: `act: { sub: "staff_user_42", iss: "https://internal.support.example.com" }`. The outer `sub` remains the impersonated user, so authorization checks naturally use the impersonated identity.

Should impersonation tokens have shorter expiry?expand_more

Almost always yes. A standard session token might live for 30 minutes; an impersonation token should live for 5–15 minutes to limit damage if a staff workstation is compromised mid-session. Couple this with a hard cap (e.g. session ends after 1 hour regardless of refresh).

What audit logging do regulators expect?expand_more

For SOC 2, ISO 27001, and most privacy regimes: every impersonation action must be logged with both the actor (the staff member) and the subject (the customer), the reason for impersonation, the duration, and the actions taken. The audit log entries must be tamper-evident.

Short access tokens limit the blast radius of a leak. Long tokens are convenient. Here's how to pick a number, with reasoning.

tenant_id vs sub: where to put tenant context in a JWT

Why conflating tenant identity with user identity in the sub claim is a multi-tenant anti-pattern, and the conventions that work instead.