Secure User Impersonation in Keycloak for Support Teams

Last updated: July 2026

Keycloak has a built-in impersonation feature that lets an authorized user start a browser session as another user directly from the admin console. You grant it with least privilege by assigning the impersonation client role on the realm-management client rather than full realm admin rights. Every impersonation generates an IMPERSONATE admin event that you can ship to a SIEM or alerting pipeline. The important constraint to understand before you roll this out: the impersonator’s own browser session is replaced by the target user’s session for the duration of the impersonation, so it is an operator action, not a per-request programmatic switch.

Support teams dealing with user-reported issues face a recurring dilemma: the fastest way to reproduce a problem is to see exactly what the user sees, but handing out admin credentials to do that is an unacceptable security risk. Questions about how to solve this properly appear frequently on GitHub (issue #20252) and Keycloak Discourse thread #25226. This post walks through Keycloak’s built-in answer, how to scope it correctly, how to audit it, and what its limits are.

What Keycloak impersonation actually does

Keycloak’s impersonation feature, documented in the Keycloak Server Administration Guide, works at the realm level. When a user with the impersonation role triggers it, Keycloak:

Ends the impersonator’s current session tokens for that realm.
Creates a new SSO session scoped to the target user’s identity.
Redirects the impersonator’s browser to the realm’s account console (or the application root) as the target user.
Records an IMPERSONATE admin event containing the impersonator’s ID, the target user’s ID, the source IP, and a timestamp.

The impersonator is not the target user at the database level. Keycloak issues tokens with sub equal to the target user’s ID, so any downstream application relying on JWT claims will see the target user’s identity, group memberships, and roles exactly as they exist in Keycloak. That makes it genuinely useful for reproducing permission problems.

To trigger impersonation from the admin console: navigate to Realm > Users, open the target user’s record, and click the Impersonate button in the top-right action area. Keycloak will ask for confirmation and then replace the current browser session.

Granting impersonation with least privilege

The default installation gives the admin realm role the ability to impersonate anyone. Giving support staff the admin role to access impersonation is not acceptable — admin includes the ability to delete users, change passwords, and modify realm settings. Instead, assign only the impersonation client role.

This is part of Keycloak’s fine-grained admin permissions model, and it is the right tool for scoping operator access. Understanding how these client roles compose is covered in more depth in our post on fine-grained authorization in Keycloak.

Step-by-step: creating a scoped support role

Step 1 — Create a dedicated support group or role

In the admin console, go to Realm > Groups and create a group named support-agents. You will assign real-user accounts to this group rather than granting roles directly to individual users, which makes revocation simpler.

Step 2 — Open the realm-management client

Navigate to Realm > Clients and click on realm-management. This is a built-in confidential client that Keycloak uses internally to represent realm-level management permissions.

Step 3 — Find the impersonation role

Click the Roles tab on the realm-management client. You will see a list that includes:

manage-users
view-users
impersonation
query-users
several others

The impersonation role is the only one required for support staff to use the Impersonate button. Do not assign manage-users unless you also want them to be able to edit user attributes and reset passwords.

Step 4 — Assign the role to the support group

Go back to Realm > Groups, open the support-agents group, click the Role Mappings tab, switch to Client Roles, select realm-management from the client dropdown, and move impersonation to the Assigned Roles column.

Step 5 — Verify

Log in to the admin console as a user who is a member of support-agents but has no other admin roles. Navigate to Realm > Users, open any user, and confirm the Impersonate button is visible and functional. Confirm that the Realm Settings, Clients, and Identity Providers menus are either absent or read-only.

The resulting permission set lets support staff:

Search for users by name or email
View user attributes and group memberships
Trigger impersonation

It does not let them:

Change passwords or credentials
Edit user attributes
Modify realm or client configuration
Create or delete users

This is the principle of least privilege applied to Keycloak’s internal role model, which connects directly to the broader discussion of RBAC design.

Restricting who can impersonate whom

A flat impersonation role grants the ability to impersonate any user in the realm, including other admin users. For most support teams that is too broad. Keycloak 26.x offers two mechanisms to tighten this.

Fine-grained admin permissions (recommended for Keycloak 26.x)

Keycloak’s fine-grained admin permissions allow you to attach policies to specific resources such as individual users or groups. To restrict impersonation to a subset of users:

Enable fine-grained admin permissions: navigate to Realm > Realm Settings > General and toggle Admin Fine Grained Authz on.
Go to Realm > Users, open the target user (or a group of users), and click the Permissions tab.
Enable permissions for that user or group.
Edit the impersonate scope policy to require a specific role, group membership, or other condition that your support agents satisfy.

With this approach you can model rules such as “agents in the tier-1-support group can only impersonate users who are members of the standard-plan group, not users with the admin realm role.”

Preventing impersonation of admin users

At a minimum you should prevent support staff from impersonating realm administrators. Fine-grained admin permissions let you attach a deny policy to admin users. Alternatively, if your admin accounts are in a dedicated group, you can set a policy that prevents impersonation of any user in that group.

Both approaches reduce the blast radius if a support account is compromised. This is directly relevant to reducing insider risk with IAM controls.

Auditing every impersonation

Impersonation without an audit trail is an internal control failure. Keycloak records impersonation under Admin Events, not user login events. You need to ensure admin events are enabled and retained.

Enabling admin events

In the admin console, go to Realm > Events > Config tab:

Set Save Events to On under the Admin Events Settings section.
Enable Include Representation if you want the full payload of what changed.
Set a reasonable Expiration — 90 days is a common compliance baseline; adjust to your data-retention policy.

Once enabled, every impersonation generates an event with:

Operation Type: ACTION
Resource Type: USER
Auth Details: the impersonator’s user ID, realm, client, and IP address
Resource Path: users/{targetUserId}/impersonation

Viewing impersonation events

Navigate to Realm > Events > Admin Events tab. Filter by Resource Type = USER and Operation Type = ACTION. Each impersonation row will show the resource path users/{id}/impersonation, making it easy to identify.

Forwarding to a SIEM

Storing events only in Keycloak’s built-in store is not sufficient for security monitoring — events can be lost on database failure and they are not searchable at scale. Forward them to a SIEM or log aggregator. Our complete guide on Keycloak auditing and event logging covers the HTTP event listener, the Kafka event listener, and log-based forwarding patterns in detail.

For impersonation specifically, configure an alert rule that fires whenever a USER / ACTION / users/*/impersonation admin event arrives. High frequency or off-hours impersonation activity is a signal worth triaging immediately.

Security cautions

The impersonation role is sensitive and should be treated accordingly:

Alert on every IMPERSONATE event. Volume matters less than awareness. Even a single unexpected impersonation event during a weekend should generate a ticket.

Rotate access regularly. Impersonation rights should be granted on a just-in-time basis where operationally feasible. Consider a workflow that adds a user to the support-agents group for a session window and removes them afterward.

Do not allow self-impersonation loops. Keycloak prevents a user from impersonating themselves, but ensure your monitoring would catch any attempt to cycle through impersonation to escalate from a support account to an admin account (which fine-grained policies should block).

Separate the support admin console from your production admin console. If your realm has a dedicated admin console URL, consider restricting access to that URL at the network layer for non-admin users. Support agents using impersonation only need access to the standard admin console, which can be a separate WP host or subdomain.

Log the impersonator’s IP address. Keycloak captures this in the admin event auth details. Cross-reference against your VPN or office IP ranges if you have them. An impersonation from an unexpected geography is a high-severity signal.

The principle here overlaps with Keycloak authorization services policy design — access to sensitive operations should be policy-controlled and monitored, not simply role-gated.

Limitations and gotchas

Understanding what impersonation cannot do is as important as knowing how to enable it.

The impersonator’s session is replaced, not duplicated. When a support agent clicks Impersonate, their own admin console session ends and their browser becomes the target user’s session. They cannot maintain two sessions simultaneously in the same browser profile. Use a separate browser or incognito window if they need to return to the admin console quickly.

Impersonation ends when the browser is closed or the session times out. The target user’s normal session timeout applies. The impersonator does not have a separate timeout. If a support agent walks away from the machine, the session can expire and they will need to re-authenticate (and re-impersonate) to continue.

It is an admin console action, not a programmatic per-request switch. Impersonation is not the same as token exchange or acting-as headers at the API level. It is a UI operation for human support agents. If you need programmatic user context switching in a service-to-service flow, look at the OAuth 2.0 token exchange specification instead.

Impersonation does not carry over MFA challenges for the target user. The session is created server-side by Keycloak, bypassing the normal authentication flow including OTP prompts. This is expected behavior but worth documenting in your internal runbooks so support staff are not confused when they land in a session without seeing an MFA prompt.

Not all events are generated for impersonated sessions. Because the session is created server-side, some authentication flow events (like LOGIN) may differ from what a real user login produces. Check your event stream behavior in a staging environment before relying on it for user debugging.

Alternative: read-only support views

If your main goal is letting support staff see what a user sees rather than act as them, consider a read-only alternative:

User lookup via Admin API: Grant view-users and query-users roles. Support staff can search for users and view their attributes, roles, and group memberships without ever touching the user’s session.
Custom support portal: Build a thin internal tool that calls the Keycloak Admin API read endpoints and displays user profile data, role assignments, and recent login events. This avoids giving support staff any admin console access at all.
Session inspection: Navigate to Realm > Users > {user} > Sessions to see active sessions, clients, and IP addresses without impersonation.

These approaches satisfy a large fraction of “show me what the user is experiencing” questions without the security surface of full impersonation. Reserve impersonation for cases where you genuinely need to reproduce a UI or permission issue that cannot be diagnosed from user data alone.

Setup checklist

Use this checklist before enabling impersonation in a production realm:

[ ] Create a dedicated group for support agents (e.g., support-agents)
[ ] Assign only the impersonation client role from realm-management to that group
[ ] Verify the group does NOT have manage-users, realm-admin, or manage-realm
[ ] Enable Admin Events under Realm > Events > Config
[ ] Set an event retention period aligned with your compliance requirements (90 days minimum)
[ ] Configure event forwarding to a SIEM or external log store
[ ] Create an alert for any USER / ACTION / impersonation admin event
[ ] Enable fine-grained admin permissions if you need to restrict who can impersonate whom
[ ] Add a deny policy to prevent impersonation of admin-group users
[ ] Document the impersonation procedure in your internal support runbook
[ ] Test impersonation in a staging realm before enabling in production
[ ] Review and revoke access after each support session if using just-in-time grants

Frequently asked questions

How do I let support log in as a user in Keycloak?

Navigate to the admin console, go to Realm > Users, open the target user’s record, and click Impersonate. For this to work, the support agent must have the impersonation client role from the realm-management client. They do not need full realm admin access — only this specific role.

How do I give impersonation rights without full admin?

Assign the impersonation role from the realm-management client directly to the user or to a group that the user belongs to. In the admin console: Clients > realm-management > Roles lists all available management roles. Map only impersonation (and optionally view-users and query-users for searching) to your support group. Do not assign manage-users or any manage-* roles unless that access is explicitly required.

Is Keycloak impersonation audited?

Yes. Every impersonation generates an admin event with operation type ACTION, resource type USER, and a resource path of users/{targetUserId}/impersonation. The event includes the impersonator’s user ID, their IP address, and a timestamp. Admin events must be enabled under Realm > Events > Config before they are persisted. See our full Keycloak event logging guide for retention and forwarding options.

Can I restrict which users a support agent can impersonate?

Yes, using Keycloak’s fine-grained admin permissions (available in the default Keycloak 26.x distribution). Enable fine-grained admin authz in Realm Settings, then attach resource-level policies to specific users or groups to control which subjects are available for impersonation. This lets you prevent support agents from impersonating admin accounts or users outside their assigned customer segment.

What happens to the support agent’s session when they impersonate someone?

The agent’s current admin console session is replaced by the target user’s session in that browser tab. They are effectively logged out of the admin console for the duration. To return to the admin console, they must log out of the impersonated session (which ends it) and log back in with their own credentials. Using a separate browser profile or incognito window for the admin console avoids disruption.

Conclusion

Keycloak’s built-in impersonation is a well-designed feature when configured correctly. The key points: grant only the impersonation client role rather than full admin, use fine-grained permissions to restrict the scope of who can be impersonated, enable admin events and forward them to your SIEM, and alert on every impersonation action. Treat the impersonation role as a privileged access credential, not a convenience setting.

If you want a managed Keycloak environment where admin event forwarding, role management, and fine-grained permissions are pre-configured and monitored, Skycloak handles the operational overhead so your team can focus on building instead of configuring.