Impersonation in Keycloak

Overview

Keycloak includes an impersonation feature that allows administrators (or users with the proper role) to log in as another user without knowing their credentials. This is particularly useful for troubleshooting user issues, reproducing bugs, or assisting end-users.

When impersonating, the admin temporarily assumes the identity of the target user and inherits their permissions, roles, and access rights. Because impersonation grants direct access to user accounts, it should be used with caution and monitored carefully.

Use Cases

IAM (Internal Identity and Access Management)

• Troubleshooting access issues for employees or administrators.
• Validating role-based access without requesting the user’s password.
• Supporting onboarding by walking through account features as the user.

CIAM (Customer Identity and Access Management)

• Helping customers resolve authentication or authorization problems.
• Investigating reported bugs in a live environment (with strict auditing).
• Assisting with configuration or feature walkthroughs for end-users.

Pros & Cons

Pros

• Simplified Support: Admins can quickly reproduce user issues without back-and-forth communication.
• No Password Disclosure: Admins do not need to request or reset user credentials.
• Time Saving: Faster troubleshooting and bug resolution.

Cons

• Security Risk: Admins gain direct access to user accounts and data, which must be tightly controlled.
• Audit Requirements: Without logging, impersonation may reduce accountability.
• Potential Misuse: If roles are misconfigured, unauthorized impersonation could occur.

Supported by Keycloak

Yes, natively supported and configurable on Managed Keycloak by Cloud-IAM.

Configuration

Impersonation for Admins

By default, impersonation can be performed by Keycloak administrators once the role is assigned.

1. Log in to the Keycloak Admin Console.
2. Select the realm where you want to impersonate a user.
3. Navigate to Users and search for the target account.
4. Open the user profile
5. Select Action dropdown list and click Impersonate
6. A new browser tab will open, and you will be logged in as the selected user.

Keycloak Console - Impersonation for Admins

Logout after impersonation

Always remember to log out after impersonation to avoid accidental actions under another user’s identity.

Impersonation by Role (e.g., Manager Role)

In some organizations, certain roles (like Manager) may need the ability to impersonate users, without having full admin privileges. Keycloak allows assigning the impersonation role from the realm-management client to non-admin users.

This guide explains how to allow a manager to impersonate users only within a single realm.

Step 1 — Admin must assign impersonation Role to the Manager

1. Log in to the Keycloak Admin Console as a realm admin
2. Select the target realm (e.g., acme)
3. Navigate to Users and select the manager user
4. Go to the Role Mappings tab
5. Click on Filter by clients
6. Select **realm management** impersonation - role_impersonation
7. Assign the role impersonation to the manager
8. Confirm the assignment

This role allows impersonation only for users in the same realm. The manager will not see or access users from other realms.

Keycloak Console - Impersonation for Admins

Step 2 — Manager Logs in to Realm Console

1. Open the URL https://your-domain.cloud-iam.com/auth/realms/sales/
2. The manager logs in using their credentials
3. Navigate to Users and search for the target account.
4. Open the user profile
5. Select Action dropdown list and click Impersonate
6. A new browser tab will open, and you will be logged in as the selected user.

The manager can now perform actions as the user for testing, troubleshooting, or support purposes, without needing full admin access.

Keycloak Console - Impersonation for Manager

Resources

• Deploy my Keycloak on Cloud-IAM
• Keycloak Documentation – Impersonation