# User access control

This guide shows how to control which users can access an application in OpenIAM. Access can be granted **explicitly** to a user or **implicitly** through a role or group.

In OpenIAM, every application is represented as a **Resource**. When you create an Authentication Provider, OpenIAM also creates a resource of type `AUTH_PROVIDER`. A user can sign in to the application only if they have access to that resource — either directly or through a role or group.

{% code overflow="wrap" %}

```
Access paths:

User ──────────────────► Resource (Application) [explicit]

User ─► Role ──────────► Resource (Application) [implicit via role]

User ─► Group ─────────► Resource (Application) [implicit via group]

User ─► Group ─► Role ─► Resource (Application) [implicit via group → role]
```

{% endcode %}

* **Explicit** — the resource is assigned directly to the user.
* **Implicit** — the resource is inherited by the user through a role or group they belong to.

All paths are equivalent from an access-check perspective — the user gains access regardless of which path was used.

{% stepper %}
{% step %}

### Create the Authentication Provider

If you have not already created the provider, go to **Webconsole** → **Access Control** → **Authentication Providers** → **+ New Provider**.

Choose the appropriate type and complete the configuration. For provider setup details, see [Configuring SSO](/federation/configuring-sso-1.md) and [OIDC and OAuth integration](/federation/oidc-and-oauth-integration.md).

Once saved, the provider's associated resource becomes available for entitlement assignment.
{% endstep %}

{% step %}

### Locate the application resource

Every Authentication Provider is backed by a resource. The quickest way to find it is directly on the provider's edit page — a **Linked to Resource** field near the top shows the associated resource name as a clickable link that opens the resource.

You can also search for it in **Webconsole** → **Access Control** → **Resources**.

Search by the provider name. The resource type will be `AUTH_PROVIDER`. Open it to confirm it is the right one — the resource name matches the Authentication Provider name.

This resource is what you assign to users, roles, or groups in the steps below.
{% endstep %}
{% endstepper %}

## Granting access

### Option A — Explicit: User → Resource

Assigns access directly to a single user without involving any role or group. Best for one-off or exception cases.

**From the resource side**, go to **Webconsole** → **Access Control** → **Resources** → \[select the application resource] → **Entitlements** → **Users** → **+ Add User**.

Search for the user, select them, optionally set access rights and date range, then confirm.

**From the user side**, go to **Webconsole** → **User Admin** → **User Search** → \[find and open the user] → **User Entitlements** → **Resources** → **+ Add Resource**.

Search for the application resource, select it, and confirm.

### Option B — Implicit via Role: User → Role → Resource

The user inherits access to the application through a role. Best for applications shared by a well-defined job function (e.g., all Finance staff access the Finance portal).

{% stepper %}
{% step %}

### Assign the resource to the role

Go to **Webconsole** → **Access Control** → **Roles** → \[select or create the role] → **Entitlements** → **Resources** → **+ Add Resource**.

Search for the application resource and confirm.
{% endstep %}

{% step %}

### Assign the role to the user

Go to **Webconsole** → **User Admin** → **User Search** → \[find and open the user] → **User Entitlements** → **Roles** → **+ Add Role**.

Search for the role and confirm.

Any user assigned this role automatically gains access to the application.
{% endstep %}
{% endstepper %}

### Option C — Implicit via Group: User → Group → Resource

The user inherits access to the application through a group. Best for team- or project-based access where membership changes frequently.

{% stepper %}
{% step %}

### Assign the resource to the group

Go to **Webconsole** → **Access Control** → **Groups** → \[select or create the group] → **Entitlements** → **Resources** → **+ Add Resource**.

Search for the application resource and confirm.
{% endstep %}

{% step %}

### Add the user to the group

Go to **Webconsole** → **Access Control** → **Groups** → \[select the group] → **Members** → **+ Add User**.

Or, from the user's side:

Go to **Webconsole** → **User Admin** → **User Search** → \[find and open the user] → **User Entitlements** → **Groups** → **+ Add Group**.

Any user in the group automatically gains access to the application.
{% endstep %}
{% endstepper %}

## Removing access

Removal mirrors assignment. Go back to the same entitlement location and click **Remove**.

<table><thead><tr><th width="216.66668701171875">What to undo</th><th>Where to go</th></tr></thead><tbody><tr><td>Explicit user → resource</td><td>User → Entitlements → Resources, or Resource → Entitlements → Users</td></tr><tr><td>User from role</td><td>User → Entitlements → Roles</td></tr><tr><td>Role from resource</td><td>Role → Entitlements → Resources</td></tr><tr><td>User from group</td><td>Group → Members, or User → Entitlements → Groups</td></tr><tr><td>Group from resource</td><td>Group → Entitlements → Resources</td></tr></tbody></table>

{% hint style="info" %}
Removing a user from a role or group removes all implicit access granted solely through that role or group. If the user also had explicit access, that must be removed separately.
{% endhint %}

## Temporary access

All assignment dialogs support optional **Start Date** and **End Date** fields (format: `MM/dd/yyyy`). Setting an end date creates a time-limited entitlement that automatically expires — useful for contractors, project-based access, or cover periods.

Leave both fields blank for permanent access.

## SelfService access request

Users can also request access through **SelfService** → **Access Request** → **Browse Catalogue** → \[find the application] → **Request**.

If the application resource has an **approval workflow** configured, the request is routed to the appropriate approver(s). Once approved, the entitlement is created automatically using the same assignment mechanism described above.

***

## API Endpoints Reference

All entitlement operations are available via REST for automation or bulk provisioning.

### Assign entitlements

<table><thead><tr><th width="278.66668701171875">Operation</th><th width="100.3333740234375">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td>User → Resource (explicit)</td><td>POST</td><td><code>/rest/api/users/entitlements/addUserToResource</code></td></tr><tr><td>User → Role (implicit via role)</td><td>POST</td><td><code>/rest/api/users/entitlements/addUserToRole</code></td></tr><tr><td>User → Group (implicit via group)</td><td>POST</td><td><code>/rest/api/users/entitlements/addUserToGroup</code></td></tr><tr><td>Role → Resource</td><td>POST</td><td><code>/rest/api/resources/addRoleToResource</code></td></tr><tr><td>Group → Resource</td><td>POST</td><td><code>/rest/api/resources/addGroupToResource</code></td></tr></tbody></table>

**Common parameters** (form-encoded or JSON body):

<table><thead><tr><th width="240.33331298828125">Parameter</th><th width="117">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>userId</code> / <code>roleId</code> / <code>groupId</code></td><td>Yes</td><td>ID of the subject being granted access</td></tr><tr><td><code>resourceId</code> / <code>roleId</code></td><td>Yes</td><td>ID of the target resource or role</td></tr><tr><td><code>rights[]</code></td><td>No</td><td>Array of Access Right IDs to attach</td></tr><tr><td><code>startDate</code></td><td>No</td><td>Start of access window (<code>MM/dd/yyyy</code>)</td></tr><tr><td><code>endDate</code></td><td>No</td><td>End of access window (<code>MM/dd/yyyy</code>)</td></tr><tr><td><code>description</code></td><td>No</td><td>Free-text note on the assignment</td></tr><tr><td><code>update</code></td><td>No</td><td><code>true</code> to update an existing assignment instead of creating a new one</td></tr></tbody></table>

### Remove entitlements

<table><thead><tr><th width="234">Operation</th><th width="119.6666259765625">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td>User ← Resource (explicit)</td><td>DELETE</td><td><code>/rest/api/users/entitlements/removeUserFromResource/{userId}/{resourceId}</code></td></tr><tr><td>User ← Role</td><td>DELETE</td><td><code>/rest/api/users/entitlements/removeUserFromRole/{userId}/{roleId}</code></td></tr><tr><td>User ← Group</td><td>DELETE</td><td><code>/rest/api/users/entitlements/removeUserFromGroup/{userId}/{groupId}</code></td></tr><tr><td>Role ← Resource</td><td>DELETE</td><td><code>/rest/api/resources/removeRoleFromResource/{resourceId}/{roleId}</code></td></tr><tr><td>Group ← Resource</td><td>DELETE</td><td><code>/rest/api/resources/removeGroupFromResource/{resourceId}/{groupId}</code></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs-beta.openiam.com/access-control/user-access-control.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.