User Impersonation

This guide will cover user impersonation within Descope. This article includes an overview of the concept of user impersonation, how to create a Descope flow to prompt a user to allow impersonation consent, and how to create a Descope flow to impersonate a user.

Descope flows support user impersonation; only users with the Impersonate permission can impersonate other users. You will need to create or update an existing role to include this permission. For more information on roles and permissions within Descope, you can review the Authorization docs.

User Impersonation Overview

User impersonation is a feature that enables application administrators to temporarily sign in and interact with your application as another user. During the impersonated session, the application perceives the impersonating user as the impersonated one. The impersonating user inherits all rights and privileges of the impersonated user, making them indistinguishable in that context.

Use Cases

This capability can be instrumental in various scenarios:

• Troubleshooting: It allows application administrators to experience issues firsthand as reported by users, facilitating more effective problem resolution.
• Testing: Developers and QA teams can validate user-specific functionalities and roles without needing the original user's login credentials.
• User Support: It aids in assisting users directly, especially when they encounter complex issues.

Security and Ethics

With great power comes great responsibility. Best practices for user impersonation include:

• User Consent: Seek permission from the user before initiating the impersonation. This not only respects their privacy but also ensures transparency in operations.
• Limited Access: Grant impersonation permissions judiciously. Only trusted personnel, such as specific administrators or support staff, should have this capability.
• Audit Trails: Descope logs impersonation logins within the Audit Trail as a LoginSucceed action with the method being Impersonate. These audit messages will include the impersonating user ID as well as the impersonated user ID.
• Awareness: Make users aware of the impersonation feature and its purpose, ensuring they understand its utility and potential risks.

Remember, user impersonation is a powerful tool but must be used thoughtfully and ethically to ensure the security and trust of your users.

Gather User Consent with Descope Flows

Create the User Consent Flow

Before the user can grant consent, the user must be authenticated. The example flow below re-authenticates the user utilizing magic link and Google OAuth. If the user is already logged in, and this flow is embedded within your application, this login-in is essentially a step-up or MFA action.

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 then edit the action to configure the Consent Expiration In Hours.

Embed and Use the Consent Flow

Once the flow has been created, you will need to embed this flow within your application. The process of embedding this flow is the same as how you would embed other flows, for which you can find example code within the Getting Started guide. When you embed the flow within your application, you will use the ID of the flow you created.

Once you embed the flow, you can then test it. Once the consent has been granted, you will be able to view the consent expiration within the User's page within the Descope console.

Impersonate a User with Descope Flows

Create the User Impersonation Flow

You will need to create a flow that allows you to impersonate a user. For this example, the user will be prompted to log in as a user which has the Impersonate permission.

Once you have the base of your flow, the next step is to create a screen with the Impersonated User input field within it. This field will take the login ID of the user you wish to impersonate.

Add the User / Impersonate action to the flow by clicking the + in the top left of the Descope flow editor. Once added, connect within the flow accordingly. You can bypass consent on this action as well if you edit the action and uncheck Validate user consent. This is not recommended when running in a production environment with a user who is unaware they are being impersonated.

Embed and Use the Impersonation Flow

Once the flow has been created, you will need to embed this flow within your application. The process of embedding this flow is the same as how you would embed other flows, for which you can find example code within the Getting Started guide. When you embed the flow within your application, you will use the ID of the flow you created.

Only users with the Impersonate permission can impersonate other users. You will need to create or update an existing role to include this permission. For more information on roles and permissions within Descope, you can review the Authorization docs.

After you have successfully logged in and impersonated a user, you will see that you are now logged in as that user. You can validate that the session JWT is also for that user by parsing it with the Validate Session API endpoint.

You can also then see that you successfully impersonated that user by searching the Audit Trail for the string Impersonate.

Impersonated User JWT

After the user is successfully impersonating the user, the JWT will include the impersonator's user ID within the act[sub].

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