> 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/grant-user-administration.md).

# Grant access to user administration

Grant administrators access to a user's profile, challenge responses, related accounts, IT policy consent history and delegation filter in Webconsole, with the PBAC policy those screens now require.

## What this is, and when you need it

Several Webconsole screens act on one user's record: the full profile, the security challenge responses, related accounts, the IT policy consent history and the delegation filter. Each one is now guarded by a policy-based access control (PBAC) policy. An administrator can use these screens for a user only if an `ACTIVE` PBAC policy allows it.

You are here if administrators are refused on those screens after an upgrade, or if you want to give a role other than Super Security Admin some or all of them. You are not here to limit *which users* an administrator can find in search. That is [Scope a delegated administrator](/administration-guide/identities/delegated-administration.md).

{% hint style="warning" %}
**The check fails closed.** If no policy allows the request, the screen is refused with a 401, including when the PBAC service cannot answer. OpenIAM ships a policy that grants every one of these actions to the **Super Security Admin** role. Any other administrator is refused until you write a policy for them.
{% endhint %}

## At a glance

|                          |                                                                                                     |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| **You will end up with** | An `ACTIVE` PBAC policy that grants user-administration actions to the administrators who need them |
| **Where**                | Webconsole → PBAC policies                                                                          |
| **You need first**       | Permission to author PBAC policies, and the id of the role you are granting to                      |
| **Takes**                | A few minutes per policy                                                                            |
| **Reversible**           | Yes. Deprecate the policy, or make an earlier version current                                       |

## What each screen asks for

Each decision asks: may **this administrator** perform **this action** on **this user**? The principal is the administrator whose session sent the request. The resource is the user whose record is open, an `Openiam::User::Human`. The actions are in the `Openiam::UserManagement::Action` namespace:

| Action                     | What it allows                                                                                      |
| -------------------------- | --------------------------------------------------------------------------------------------------- |
| `VIEW_USER`                | Open the user's full profile                                                                        |
| `VIEW_CHALLENGE_RESPONSES` | View the user's security challenge questions and answers                                            |
| `MANAGE_RELATED_ACCOUNTS`  | Link or unlink a [related or primary account](/administration-guide/identities/related-accounts.md) |
| `VIEW_IT_POLICY_HISTORY`   | View the user's IT policy consent history, and check whether an IT policy is approved               |
| `RESET_IT_POLICY_HISTORY`  | Revoke one of the user's IT policy consents                                                         |
| `VIEW_DELEGATION_FILTER`   | View the user's delegation filter                                                                   |
| `EDIT_DELEGATION_FILTER`   | Change the user's delegation filter                                                                 |

## Grant every action to a role

In the policy form builder, choose **Any user management action** in the action list. It writes the same `action is Openiam::UserManagement::Action` condition as the Cedar text below, and the shipped policy opens in the form.

{% stepper %}
{% step %}
Create a PBAC policy as described in [Create a policy](/administration-guide/pbac/create-a-policy.md).
{% endstep %}

{% step %}
Open its **Cedar text** tab.
{% endstep %}

{% step %}
Enter the policy text, replacing `<role-id>` with the id of the role you are granting to. The shipped policy is this text with role `9`, Super Security Admin:

{% code overflow="wrap" %}

```
permit (
    principal in Openiam::Role::"<role-id>",
    action,
    resource is Openiam::User::Human
)
when {
    action is Openiam::UserManagement::Action
};
```

{% endcode %}
{% endstep %}

{% step %}
Set the status to `ACTIVE`.
{% endstep %}

{% step %}
Set the enforcement mode to `FULL`. A `DRAFT` policy is never evaluated, and a `SHADOW` policy is only observed, so neither one grants anything.
{% endstep %}

{% step %}
Select the version and choose **Make current**. Adding a version does not put it in force until you do this.
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
Put the action test in the `when` clause, not in the policy head. Cedar will not parse a policy whose head names an action type other than one called `Action`. A policy that does not compile grants nothing, and nothing warns you.
{% endhint %}

## Grant only some actions

To give a role part of this access, name the actions instead of the whole namespace. In the policy form builder, pick them from the action list, where they appear as **User management - View user**, **User management - Reset IT policy history** and so on. In the Cedar editor, this example lets a help desk role view a profile and its IT policy history, but not the challenge responses, and lets it change nothing:

{% code overflow="wrap" %}

```
permit (
    principal in Openiam::Role::"<help-desk-role-id>",
    action,
    resource is Openiam::User::Human
)
when {
    action == Openiam::UserManagement::Action::"VIEW_USER"
    || action == Openiam::UserManagement::Action::"VIEW_IT_POLICY_HISTORY"
};
```

{% endcode %}

To keep a population out of reach whatever else is granted, add a `forbid`. A forbid wins over every permit. This one protects Super Security Admins from being administered by anyone through these screens:

{% code overflow="wrap" %}

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

{% endcode %}

## Verification

* **Each decision** is recorded as a `PBAC_REQUEST` audit event with the principal, the resource, the action and the policies that decided it. [Trace a decision](/administration-guide/pbac/trace-a-decision.md) explains how to read one.
* **Before you enforce a new grant**, simulate it against administrators who should be covered and a few who should not. [Simulate a policy](/administration-guide/pbac/simulate-a-policy.md) evaluates a version that is not yet in force.

## When it goes wrong

| What you see                                                                             | What it means                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| An administrator who used these screens before the upgrade now gets a 401                | Expected if they are not in Super Security Admin. The shipped policy grants only that role. Write a policy for their role                                                                                          |
| Refused with `no applicable policy` in the decision log                                  | No `ACTIVE` policy matched. Check the policy is `ACTIVE`, has a current version, and is not in `SHADOW` mode                                                                                                       |
| Refused with `denied by policy`                                                          | A policy matched and did not allow it. A `forbid` may be winning, or a `when` clause is false                                                                                                                      |
| Refused straight away, with a decision-service error in the log                          | The PBAC service could not answer, and the check refused the request. Confirm the PBAC service is running, then see [Diagnose a failed operation](/administration-guide/operations/diagnose-a-failed-operation.md) |
| Revoking a consent fails with "This consent record does not belong to the selected user" | The consent record named in the request belongs to a different user than the one open on screen. Reload the user's IT policy history and try again                                                                 |

## Related

* [The policy model](/administration-guide/pbac/policy-model.md): statuses, versions, enforcement modes and the entities Cedar can see
* [Create a policy](/administration-guide/pbac/create-a-policy.md): authoring a PBAC policy in the form or the Cedar editor
* [Roll a policy out safely](/administration-guide/pbac/roll-out-a-policy.md): shadow and partial enforcement before a full rollout
* [Impersonate a user](/administration-guide/identities/impersonate-a-user.md): the other Webconsole capability granted by a shipped PBAC policy
* [Manage related accounts](/administration-guide/identities/related-accounts.md): the screen guarded by `MANAGE_RELATED_ACCOUNTS`


---

# 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/grant-user-administration.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.