Impersonation

Impersonation lets account admins log into your application as any of your users with a single click from the Authalla dashboard. Use it to reproduce bugs from a customer's exact perspective, walk a user through a workflow, or investigate a support ticket—without ever asking for a password or running a screen share.

Every impersonated session is short-lived, never receives a refresh token, and is fully recorded in your audit log alongside the admin who started it.

Why setup is easy

Authalla drives the entire flow through your existing OAuth2 login. There is no custom code to write in your application, no impersonation SDK, no special token type to handle, and no second login flow to maintain. You enable impersonation for a client by setting one URL on it—everything else is your normal sign-in.

The only requirement is that the OAuth2 client you want to impersonate against has an initiate_login_uri configured.

Set initiate_login_uri on the client

initiate_login_uri is a standard OpenID Connect client metadata field (spec). It points to an endpoint in your application that starts an OAuth2 login flow.

In the Authalla dashboard go to OAuth Clients → (select client) → Overview and fill in Initiate login URI. It should point at a public route in your app—for example:

https://app.example.com/initiate-login

That route just needs to kick off your existing OAuth2 authorization request. Most apps already have this logic behind their "Sign in" button—the impersonation endpoint can be the same handler, or a thin route that does the same thing.

A minimal handler reads iss, client_id, and (optionally) login_hint from the query string, builds the normal authorization URL (PKCE, state, scopes—exactly as you'd do for a real user), and redirects. If you already have OAuth2 working, this is a handful of lines.

// pages/initiate-login.ts (Next.js example)
import { redirect } from 'next/navigation'
import * as client from 'openid-client'

export default async function InitiateLogin({ searchParams }) {
  const issuer = new URL(searchParams.iss)
  const config = await client.discovery(issuer, searchParams.client_id)

  const codeVerifier = client.randomPKCECodeVerifier()
  const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier)
  const state = client.randomState()

  // Persist codeVerifier + state in a server-side session as you normally would
  await saveAuthSession({ codeVerifier, state })

  const authorizationUrl = client.buildAuthorizationUrl(config, {
    response_type: 'code',
    client_id: searchParams.client_id,
    redirect_uri: 'https://app.example.com/oauth/callback',
    scope: 'openid profile email',
    state,
    code_challenge: codeChallenge,
    code_challenge_method: 'S256',
    login_hint: searchParams.login_hint,
  })

  redirect(authorizationUrl.href)
}

That is the entire integration. The callback, token exchange, scopes, post-login hooks, and session creation in your app are all unchanged.

Starting an impersonation

Once a client has initiate_login_uri set, any account admin can impersonate against it:

1. Open Users → (select user) in the Authalla dashboard.
2. Click Impersonate.
3. Pick the client you want to impersonate against from the list.
4. A new tab opens, the chosen client runs its normal OAuth2 flow, and the admin is signed into your app as the target user.

The admin is identified to your application via the standard RFC 8693 act (actor) claim on the access and ID tokens, so your application code—and your application's own audit log—can always tell who really performed each action during an impersonated session.

Safety

Impersonated sessions are intentionally limited:

• No refresh tokens. Impersonated sessions are short-lived access only. When the admin closes the tab or the access token expires, the session is over—nothing renews silently in the background.
• Single-use, short-lived handoff. The grant that hands the admin into the tenant's OAuth2 domain is one-shot and expires in 60 seconds. A leaked link cannot be replayed.
• Bounded to the admin's account. Account admins can only impersonate users that belong to their own account, and only against clients in that account. There is no path for cross-account access.

Audit logging

Every impersonation is recorded in your audit log so support actions and compliance reviews always have a complete trail.

Two events are emitted:

• impersonation_started — when the admin clicks Impersonate. Records the admin's identity, the target user, the chosen client, and the tenant.
• token_issued with an impersonator_admin_user_id — when the impersonated OAuth2 flow successfully issues tokens. Records which admin is now actively acting as the user.

These events appear under Admin dashboard → OAuth2 Activity, and the admin who initiated the session is shown on every related row. See Admin dashboard for filtering and exporting options.