> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/identities/impersonate-a-user.md).

# Impersonate a user

Start a Webconsole session as another user to see exactly what they see, and grant that ability with the PBAC policy it now requires.

## What this is, and when you need it

Impersonation replaces your own Webconsole session with a session as another user, so you see precisely what they see — the menus they have, the requests they can raise, the errors they hit. It is the tool for "the user says the page is empty and I cannot reproduce it."

You are not here if you only need to act *for* someone: granting access, resetting a password or running a lifecycle action are all done from that user's record without becoming them. Reach for impersonation only when the thing you need to observe is the user's own view, because an impersonated session can do everything that user can do.

{% hint style="warning" %}
**Impersonation now requires a policy-based access control (PBAC) policy.** Every attempt is refused unless an `ACTIVE` PBAC policy permits the impersonation action for the administrator making the request. There is no property, role or entitlement that switches this off — if no policy applies, the answer is no.

If you are upgrading, read [When it goes wrong](#when-it-goes-wrong) before your administrators find out the hard way: the entitlement that used to grant impersonation no longer does.
{% endhint %}

## At a glance

|                          |                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| **You will end up with** | Your browser signed in as the target user, with your own session ended                                 |
| **Where**                | `/webconsole/impersonate`                                                                              |
| **You need first**       | An `ACTIVE` PBAC policy permitting the impersonation action, and a target user with a primary identity |
| **Takes**                | Under a minute once the policy is in place                                                             |
| **Reversible**           | Yes — sign out of the impersonated session and sign in again as yourself                               |

## Before you begin

* Confirm an `ACTIVE` PBAC policy permits the impersonation action for the administrators who need it. OpenIAM ships one that grants the **Super Security Admin** role; if your administrators sit elsewhere, write your own using [Grant access to impersonation](#grant-access-to-impersonation) below.
* Check the target user has a primary identity. Impersonation signs in as that identity, so a user without one cannot be impersonated.
* Expect to lose your own session. Impersonation ends it deliberately — see [What happens when you impersonate](#what-happens-when-you-impersonate).

## Grant access to impersonation

The decision asks one question: may **this administrator** perform **the impersonation action** on **this user**? The administrator is the principal, taken from the session of whoever clicks the button. The user being impersonated is the resource.

{% stepper %}
{% step %}
Create a PBAC policy as described in [Create a policy](/administration-guide/pbac/create-a-policy.md), and open its **Cedar text** tab.
{% endstep %}

{% step %}
Enter the policy text. This is the shipped policy, which grants impersonation of any user to the Super Security Admin role:

{% code overflow="wrap" %}

```
permit (
    principal in Openiam::Role::"9",
    action,
    resource is Openiam::User::Human
)
when {
    action is Openiam::Action::Impersonate
};
```

{% endcode %}
{% endstep %}

{% step %}
Set the status to `ACTIVE` and the enforcement mode to `FULL`. A `DRAFT` policy is never evaluated, and a `SHADOW` policy is observed rather than enforced — neither grants anybody anything.
{% endstep %}

{% step %}
Select the version and choose **Make current**. Appending a version does not put it in force; this step does.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
The action test belongs in the `when` clause, not in the policy head. Cedar refuses to parse a policy whose head names an action whose entity type is not called `Action`, so moving `action is Openiam::Action::Impersonate` up beside `principal` and `resource` makes the policy fail to compile — and a policy that does not compile grants nothing, silently.
{% endhint %}

### Narrow who can be impersonated

The shipped policy permits impersonation of *any* user, including other administrators. To restrict it, constrain the resource in the `when` clause. This example allows impersonation only of contractors:

{% code overflow="wrap" %}

```
permit (
    principal in Openiam::Role::"9",
    action,
    resource is Openiam::User::Human
)
when {
    action is Openiam::Action::Impersonate
    && resource has employeeTypeId
    && resource.employeeTypeId == "CONTRACTOR"
};
```

{% endcode %}

The `resource has employeeTypeId` guard is not optional. Cedar errors on an attribute that is not present rather than treating it as false, and an erroring policy grants nothing — see [The policy model](/administration-guide/pbac/policy-model.md).

Adding a `forbid` policy is the stronger way to protect a population, because a forbid wins over every permit no matter which policy came first:

{% code overflow="wrap" %}

```
forbid (
    principal,
    action,
    resource in Openiam::Role::"9"
)
when {
    action is Openiam::Action::Impersonate
};
```

{% endcode %}

## Impersonate a user

{% stepper %}
{% step %}
Go to **Webconsole → Impersonate**, at `/webconsole/impersonate`.
{% endstep %}

{% step %}
Search for the user you want to impersonate. The screen is the standard advanced user search, so you can filter by name, login, organization or any other search field.
{% endstep %}

{% step %}
Select the switch-account action on that user's row. The action is disabled while an impersonation is already in flight, so a second click cannot swap the session twice.
{% endstep %}
{% endstepper %}

### What happens when you impersonate

The order matters, because two of these steps are irreversible from your side:

1. The policy decision is requested. If it is not an allow, nothing else happens and you stay signed in as yourself.
2. Your own session is ended.
3. A new session is started as the target user's primary identity.
4. Your access token is revoked, so the impersonated session does not start holding a token belonging to your identity.
5. The browser is redirected into the impersonated session after a short pause that lets you read the confirmation.

To get back to your own account, sign out and sign in again as yourself. There is no "return to my session" control, because your session no longer exists.

## Verification

Prove the grant works before telling an administrator it does:

* **The decision** is recorded as a `PBAC_REQUEST` audit event carrying the principal, the resource, the action and which policies decided it. [Trace a decision](/administration-guide/pbac/trace-a-decision.md) explains how to read one, including for a refusal.
* **The impersonation itself** is recorded as an `IMPERSONATION` audit event against the target user. See [Audit actions and retention](/administration-guide/reference/audit-actions-and-retention.md).
* **Before granting it in production**, simulate the policy against the administrators you intend to cover and a few you do not. [Simulate a policy](/administration-guide/pbac/simulate-a-policy.md) evaluates a version that is not yet in force, so you can confirm the population before anything is enforced.

## When it goes wrong

| What you see                                                                        | What it means                                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Impersonation is refused for an administrator who could do it in an earlier release | Expected after upgrading. Impersonation was previously granted by an entitlement to a system-action resource, named by the `org.openiam.ui.impersonate.resource.name` property. Both the property and that check are gone. Write a PBAC policy — the entitlement no longer has any effect |
| Refused with `no applicable policy` in the decision log                             | No `ACTIVE` policy matched this request. Check the status is `ACTIVE`, that a current version is selected, and that the enforcement mode is not `SHADOW`                                                                                                                                  |
| Refused with `denied by policy`                                                     | A policy applied and did not allow it. A `forbid` may be winning, or a `when` clause is false — most often an attribute guard, because a missing attribute makes the policy error rather than match                                                                                       |
| Refused immediately, with a decision-service error in the log                       | The guard fails closed: when the PBAC service cannot answer, the request is refused rather than allowed. Check the PBAC service is running, then see [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md)                                       |
| The policy will not save, with a parse error on the action                          | The action is pinned in the policy head. Move it into the `when` clause — see the note in [Grant access to impersonation](#grant-access-to-impersonation)                                                                                                                                 |
| Impersonation is allowed but signing in as the user fails                           | The decision permitted it; the sign-in did not. The target user's primary identity is missing, disabled, or its password cannot be retrieved                                                                                                                                              |

## Related

* [Create a policy](/administration-guide/pbac/create-a-policy.md) — authoring a PBAC policy from the form or the Cedar editor
* [The policy model](/administration-guide/pbac/policy-model.md) — statuses, versions, enforcement modes and the attribute rules that decide whether a policy evaluates
* [Roll a policy out safely](/administration-guide/pbac/roll-out-a-policy.md) — shadow and partial enforcement before a full rollout
* [Trace a decision](/administration-guide/pbac/trace-a-decision.md) — reading the decision log for an allow or a refusal
* [Scope a delegated administrator](/administration-guide/identities/delegated-administration.md) — limiting what an administrator reaches without becoming another user


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/identities/impersonate-a-user.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.