OIDC SPA
GitHubHome
v5
  • Documentation
  • Release Notes & Upgrade Instructions
v5
  • Documentation
    • 🔩Installation
    • 👨‍🔧Basic Usage
    • 🔌Web API
    • ⏲️Auto Logout
    • ❗Error Management
    • 🎭Mock
    • 🔁Tokens Renewal
    • 🛡️Globally Enforce Authentication
    • 🔐User Account Management
    • 🔄Doing Something Only When a New Session is Created
    • 👨‍🔧User impersonation
    • 👮Disabeling token persistance
  • Example setups
    • 🛣️TanStack Router
    • 🛤️React Router
  • Resources
    • 🔑Keycloak Configuration Guide
    • 🍪End of third-party cookies
    • 🗝️JWT Of the Access Token
    • 💬Discord Server
    • ⬆️Migration Guides
      • ⬆️v4 -> v5
  • ⭐Sponsors
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. Documentation

User impersonation

Enable the admin of your application to login as a given user.

User impersonation should ideally be managed by the authentication server. For instance, if you are using Keycloak, you can navigate to the Admin Console, then go to: Users -> Action -> Impersonate. This allows you to access all applications within the realm as the impersonated user.

The workaround described in this documentation is intended for situations where:

  • The support team handling impersonation does not have access to the Keycloak Admin Console.

  • Hosting a custom admin app .

Imagine you have a custom admin app that allows your support team to impersonate users. With oidc-spa, you can include a special query parameter when redirecting a support team member from your admin app to your main app. This will automatically authenticates the support team member as the impersonated user.

By default, this feature is disabled. To enable it:

import { createOidc } from "oidc-spa";

const oidc = await createOidc({
    // ...
    getDoContinueWithImpersonation: async ({ parsedAccessToken })=> {
    
      const doContinue = confirm(`
        WARNING: You are about to impersonate ${parsedAccessToken.email}.
        If you don't understand why you are seeing this message please
        click cancel and contact support.  
        Someone might be trying to trick you.  
      `);
      
      return doContinue;
        
    }
});
import { createReactOidc } from "oidc-spa/react";

export const { OidcProvider, useOidc, getOidc } = createReactOidc({
    // ...
    getDoContinueWithImpersonation: async ({ parsedAccessToken })=> {
    
      const doContinue = confirm(`
        WARNING: You are about to impersonate ${parsedAccessToken.email}.
        If you don't understand why you are seeing this message please
        click cancel and contact support.  
        Someone might be trying to trick you.  
      `);
      
      return doContinue;
        
    }
});

Crafting the URL for Impersonation

After using the Keycloak API to obtain an access token, ID token, and refresh token for a user session in exchange for your admin token, you can craft the redirection URL for impersonation as follows:

(For this example, we assume you're using a JavaScript backend, but you can easily adapt it to your environment.)


const accessToken = "...";
const idToken = "...";
const refreshToken = "...";

const obj = {
    accessToken,
    idToken,
    refreshToken,
};

// NOTE: An array in case you have more than one oidc client instance in your app.
const arr = [obj];
const str = JSON.stringify(arr);
const b64 = btoa(str); // to base64

// This is the impersonation url:
const url = `https://your-app.com?oidc-spa_impersonate=${b64}`
PreviousDoing Something Only When a New Session is CreatedNextDisabeling token persistance

Last updated 7 months ago

Was this helpful?

👨‍🔧