Launch Week Day 5: Impersonation

As users interact with your application, at some point they will experience issues and get stuck. Legacy users will get lost in complex states and new users will sometimes overlook reading docs, requiring your support team to assist with troubleshooting.

Problem is that support can’t pinpoint exact issues your user is seeing unless the user screen shares or records a video. Support also needs to disregard any personal or sensitive information that users accidentally reveal when sharing their screen.

The solution is what we’re shipping today: secure, auditable, opt-in impersonation that requires no integration.

Let’s start with the best part: this new feature is free to all WorkOS users. With just a few clicks, support can impersonate a user in the dashboard and see exactly what they see, minus any sensitive data.

Secure by default

When requesting to impersonate a user, it’s mandatory to provide a justification for the request. This reason is logged and can be retrieved later in the sessions detail page by your security team for audits.

When impersonation does occur, an event is emitted, which can be delivered to your systems via webhooks.

      
{
  "id": "event_01HR8QTYRKGSPERJGZRGRN9CFZ",
  "event": "session.created",
  "data": {
    "object": "session",
    "id": "session_01HR8QXN9ET2JP0JFDWHBHMR97",
    "user_id": "user_01HR8QXMH4X8Q46349R6EQAD1D",
    "organization_id": "org_01HR8QX01S2B4JDDMKM1KMQH7E",
    "ip_address": "127.0.0.1",
    "user_agent":
      "Mozilla/5.0 (Macintosh; Intel Mac OS X) Gecko Firefox/42.0",
    "impersonator": {
      "email": "admin@foocorp.com",
      "reason": "Helping debug a customer issue."
    },
    "created_at": "2024-03-02T19:07:33.155Z",
    "updated_at": "2024-03-02T19:07:33.155Z"
  },
  "created_at": "2024-03-02T19:07:33.155Z"
}
        
      

For added security, impersonation is an opt-in option for your user, giving them control over who can access their account. From your point of view, impersonation can be globally toggled on or off in the WorkOS dashboard.

Impersonation is powered by Sessions, which we announced a few days ago. Each session is limited to 60 minutes, after which the impersonator is locked out until a new impersonation request is made.

Available immediately

No integration is required, if you’re using Sessions then you have the ability to use this new feature right now.

However, some developers may want to customize the application behavior when the current user is being impersonated. For example, to redact sensitive information in the application’s UI, or prevent the impersonator from modifying certain fields.

In these cases, the application can detect that the current user is being impersonated using the impersonator field in a successful authentication response.

      
{
  "user": {
    "object": "user",
    "id": "user_01EHWNC0FCBHZ3BJ7EGKYXK0E6",
    "first_name": "Todd",
    "last_name": "Rundgren",
    "email": "user@example.com",
    "profile_picture_url": null,
    "email_verified": true,
    "created_at": "2023-11-27T19:07:33.155Z",
    "updated_at": "2023-11-27T19:07:33.155Z"
  },
  "impersonator": {
    "email": "admin@foocorp.com",
    "reason": "Helping debug a customer issue."
  }
}
        
      

Similarly, Session access tokens have an additional act claim containing the impersonator’s email. 

      
{
  "iss": "https://api.workos.com",
  "sub": "user_01HBEQKA6K4QJAS93VPE39W1JT",
  "act": {
    "sub": "admin@foocorp.com"
  },
  "org_id": "org_01HRDMC6CM357W30QMHMQ96Q0S",
  "role": "member",
  "sid": "session_01HQSXZGF8FHF7A9ZZFCW4387R",
  "jti": "01HQSXZXPPFPKMDD32RKTFY6PV",
  "exp": 1709193857,
  "iat": 1709193557
}
        
      

Both of these will allow you to display a warning or banner in your application reminding the team member using this feature that they are impersonating another user and to be careful with the actions that they undertake. 

If you’re using the new Next.js library, you can use our provided `Impersonation` component to automatically render a warning when a user is being impersonated.

      
import { Impersonation } from '@workos-inc/nextjs';

export default function App() {
  return (
	<div>
      <Impersonation />
      {/* Your app content */}
    </div>
  );
}
        
      

For more information on how Impersonation works, refer to the documentation.

That wraps it up for day 5 of Launch Week, tomorrow is the 6th and final day where we’ll be revealing big updates to Radix Themes.