User Impersonation

User impersonation is a Descope feature that enables privileged users to act on behalf of another user.

It is particularly useful for:

• Troubleshooting: Reproduce user issues directly.
• Testing: Validate user-specific functionality without sharing credentials.
• User Support: Provide direct assistance in the user's context.

This guide explains how impersonation works, how to configure permissions, how to create and embed flows for consent, impersonation, and stopping impersonation, and how to understand and verify impersonation JWTs.

Permissions and Access Control

Only users with the Impersonate permission can impersonate other users.

This permission can be assigned in two ways:

To grant impersonation rights:

1. In the Authorization tab, create or edit a role. This can also be done programatically via SDKs or APIs as well.
2. Add the Impersonate permission to the role.
3. In the Users tab, assign the role to a user.

Tenant Level Impersonation

In Descope, impersonation privileges can be scoped to a tenant. This is useful when you want to restrict impersonation to users within a specific tenant.

If a user has a tenant-level role with the Impersonate permission, they will only be able to impersonate users within that tenant.

1. In the Authorization tab, create or edit a role (e.g., Tenant Admin). This can also be done programatically via SDKs or APIs as well.
2. Assign the Impersonate permission to that role.
3. In the Users tab, assign the role to the user for a specific tenant.

This restricts impersonation to users within that tenant.

Impersonation Flow Actions

Descope provides three Flow actions related to impersonation:

If you wish to allow/enforce user granting consent before impersonation, you can do so by adding the Update User / Impersonation consent action to the flow, described in the Gathering User Consent section.

Otherwise, skip to the Impersonating a User with Descope Flows section, to learn more about how to impersonate a user.

Gathering User Consent

Before impersonation, users can grant consent to be impersonated via a User Impersonation Consent Flow.

Create the User Consent Flow

In order to be able to grant consent to be impersonated, the user must be authenticated first.

If the user is already authenticated, the user will still have to login again to grant consent. This effectively acts as a step-up or MFA action, in this case.

To allow the user to grant consent, add the Update User / Impersonation consent action to the flow by clicking the + in the top left of the Descope flow editor.

Once added, connect within the flow accordingly, and edit the action to configure the Consent Expiration In Hours.

Once the user consent has been granted, you will be able to view the consent expiration within the User's page of the Descope console.

Impersonating a User with Descope Flows

This section covers how to create a flow that allows you to impersonate a user. If you wish to manage impersonation via SDKs or APIs, you can see our User Impersonation with SDKs guide instead.

Create the User Impersonation Flow

In your impersonation flow, you'll need to create a screen with the Impersonated User input field within it. This field will take a login ID of the user you wish to impersonate.

Afterwards, you'll need to add the User / Impersonate action in the flow after the screen.

If you wish to bypass user consent to be impersonated, you can uncheck the Validate user consent option on this action. However, this is not recommended when running in a production environment for security reasons.

Finally if you wish to allow the impersonating user to stop impersonation, you can add a path in your flow with the User / Stop Impersonation action to accomplish this.

Using the Impersonation Flow

In order to begin impersonating a user through a flow, a user who possesses the Impersonate permission must be authenticated first. See the Permissions and Access Control section above for more details on setting up the required permissions.

After the impersonator has successfully authenticated and impersonated a user, Descope will return a user token with the sub claim set to the impersonated user's ID. If you typically include additional claims in your user token, you'll need to add a Custom Claims Action to the flow to set these claims. This is described in further detail below.

You can also validate that the user was successfully impersonated by searching the Audit Trail for the string Impersonate.

Stop Impersonation in Flow

The Stop Impersonation action enables users to seamlessly switch back to their original account during an impersonation session, eliminating the need for manual logout and re-authentication.

This action can be triggered after a Load User action in the flow, utilizing the existing impersonated session.

After adding this action, once you successfully end the flow, a JWT for the user will be returned without the impersonator's user ID within act[sub].

{
  "drn": "DS",
  "exp": 1693325322,
  "iat": 1693324722,
  "iss": "P2UcQcyxrjSA3mr6y0xZKRYI5oJz",
  "rexp": "2023-09-26T15:58:42Z",
  "sub": "U2UcRpsA4DSJ8kBvp6jikPyJ3aJ8"
}

Understanding Impersonation JWTs

When impersonation succeeds, the session JWT reflects both the impersonator and impersonated user.

The impersonator's User ID is stored within the act.sub claim.

{
  "act": {
    "sub": "U2UcRpsA4DSJ8kBvp6jikPyJ3aJ8"
  },
  "sub": "U2UcRIInQ56lEhuRtxWx1NsmgxaS",
  "iss": "P2UcQcyxrjSA3mr6y0xZKRYI5oJz",
  "iat": 1693324722,
  "exp": 1693325322,
  "rexp": "2023-09-26T15:58:42Z",
  "drn": "DS"
}

Displaying Impersonator Information

When using impersonation, you may want to display information about the impersonator in your application's frontend. To access information about the impersonator, you need to read the session JWT.

In a flow, you can add information to the token by using the Custom Claims Action. Note that when user attribute custom claims (e.g. user.name) are set before the impersonation action in the flow, they reflect the impersonator. When custom claims are set after the impersonation action, they reflect the impersonated user.

It's worth noting that if you're managing your session token with cookies, the frontend will not be able to read the JWT claims to retrieve impersonator info. Therefore you'll have to manage returning this information manually from your backend, as described in the following steps:

• From the frontend, send a request including the JWT to your backend.
• In the backend, validate the JWT using one of the Backend SDKs or the API.
• Extract the impersonator's user ID from the act.sub claim in the validated JWT.
• Use the Management SDK or API to fetch the impersonator's details using the extracted user ID.
• Return the impersonator's details to the frontend for display.

Auditing

All impersonation actions are logged in the Audit Trail as LoginSucceed with method Impersonate, showing both impersonator and impersonated user IDs.