> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Opal roles

> Learn how to create custom Opal roles.

Custom Opal roles consist of granular sets of permissions which you can assign to users and groups. Use custom roles to manage users and teams with differing access requirements.

See [Special roles in Opal](https://docs.opal.dev/docs/roles-in-opal.md) for an overview of existing, reserved Opal roles—Admin, Auditor, etc.

## Requirements

To create or edit custom Opal roles, you must be an [Opal Admin](https://docs.opal.dev/docs/roles-in-opal.md).

If you self-host Opal, some permissions require a recent version. The version each newer permission group was introduced in is noted in the [Permissions](#permissions) tables below.

## Create a custom role

1. Go to the **Inventory** and search for the **Opal** app.
2. From the **Assets** tab, select **+ Custom Role**.

![The Assets tab of the Opal app in the Inventory, with the + Custom Role button highlighted](https://mintcdn.com/opalsecurity/fu-nWazMe1LxLhxi/images/docs/38e409c7bb8e2df33ce0c2f700a872828ce114a8be00eeb4e9eae9955c491bfb-custom-roles.png?fit=max\&auto=format\&n=fu-nWazMe1LxLhxi\&q=85\&s=75e7e76d58899c2c8d42963b6fae456f)

3. Start with a templated set of permissions based on an existing role—**Full admin**, **Read-only admin**, **Owner**, or **Auditor**—or select **Custom role** to start from scratch. You can add and remove granular permissions in the following step.

![The template picker with five options: full admin, read-only admin, owner, auditor, and a custom role from scratch](https://mintcdn.com/opalsecurity/KunPWigry5GIeB5g/images/docs/4e364c922bd3806e8e7ac74943c6cf0ee49964cd4146c48236b99af88ebe9365-custom-role-template.png?fit=max\&auto=format\&n=KunPWigry5GIeB5g\&q=85\&s=0eaf9eb958c559ec917a3717d096a87e)

4. Set the role's name, description, and [admin](https://docs.opal.dev/docs/configure-reviewers.md#owners), then optionally update [permissions](#permissions) for the role.

   Permissions are grouped into a tab per asset type: **Native Apps**, **Resources**, **Groups**, **Users**, **Bundles**, **Access Reviews**, **Owners**, and **Tags**. Within each tab, **General Permissions** always apply to every asset of that type, while **Scoped Permissions** can be limited to specific assets—switch the toggle from **All** to **Scoped** and pick the assets to scope to.

![The permissions step of the create custom role flow, showing the asset type tabs and the general and scoped permission sections](https://mintcdn.com/opalsecurity/cwfz1gF0tCdDARg-/images/docs/custom-role-permissions-tabs.png?fit=max\&auto=format\&n=cwfz1gF0tCdDARg-\&q=85\&s=47be3655431f3f53e212041cfd82a526)

After you save the role, add users and groups to the role from the **User Access** and **Group Access** tabs, as you would grant access to any other resource.

## View and edit a custom role

A custom role's permissions live on its **Scope** tab.

* The **All**, **Enabled**, and **Disabled** filter controls which permissions the tab lists. It defaults to **Enabled**, so a role with few permissions shows a mostly empty tab—switch to **All** to see every permission and its state.
* Select **Edit role** to change permissions or scopes, then **Save**.
* Select **Duplicate role** to start a new role pre-filled with this role's permissions, named `Copy of <role>`.

> [!NOTE]
>
> Opal's reserved roles—Admin, Auditor, Read-only Admin, and Global Requester—also have a **Scope** tab, without the **Edit role** button. Open one to see exactly which permissions it grants, or select **Duplicate role** to use it as the starting point for a custom role.

## Permissions

You can edit permissions on a custom role at any time. Permissions are non-additive, and do not depend on each other. You may need to explicitly add read permissions for edit permissions to take effect.

**Read** and **View** permissions indicate the role can access the item in the Inventory and Catalog. See [Role and visibility hierarchy](#role-and-visibility-hierarchy) for examples of how roles interact with existing settings, and [Inherited permissions](#inherited-permissions) for how a scoped permission extends to assets beneath the asset you scoped it to.

Every permission below is available on custom roles. The **Applicable roles** column lists which of Opal's reserved roles also hold the permission, where:

* **Admin Owner** refers to the Admin set on an app, resource, group, or bundle—not the Opal Admin role—and applies only to the assets they own.
* **Group Leader** refers to a [group leader](https://docs.opal.dev/docs/group-projects.md), and applies only to the groups they lead.

### Native apps

Applies to all apps:

| Permission | Description | Applicable roles |
| - | - | - |
| Create | Create apps | Admin |

Can be scoped to specific apps:

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View apps and all their resources and groups (overrides visibility groups) | Admin, Read-only Admin, Auditor, Admin Owner |
| View assignments | View all principal assignments with access to groups and resources within the apps | Admin, Read-only Admin, Auditor, Admin Owner |
| Export | Export data for any resource and group within the apps | Admin, Read-only Admin, Auditor, Admin Owner |
| Sync | Sync apps and all the entities within them | Admin, Admin Owner |
| Read all settings and request configurations | View app settings and request configurations for all their resources and groups | Admin, Read-only Admin, Auditor, Admin Owner |
| Edit settings | Edit app settings, and the settings for all their resources and groups | Admin, Admin Owner |
| Sync Settings | Edit sync settings for the apps, such as credentials and import-all | Admin |
| Add and remove tags | Edit tags for all resources and groups within the apps | Admin, Admin Owner |
| Edit request configurations | Edit request configurations for any entity within the apps | Admin, Admin Owner |
| Import | Import or create groups and resources within the apps | Admin, Admin Owner |
| Add, edit, remove users and groups | Edit groups, users, NHIs, and all related resource assignments and their dependencies | Admin, Admin Owner |
| Assign UAR reviewers | Assign users to perform access reviews for entities within the apps | Admin, Auditor, Admin Owner |
| Delete | Delete apps, and delete any group or resource within an app | Admin, Admin Owner |

### Resources

All resource permissions can be scoped to specific resources.

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View resources and, where applicable, all their child resources (overrides visibility groups) | Admin, Read-only Admin, Auditor, Admin Owner |
| View assignments | View all users and NHIs with access to the resources and, where applicable, their child resources | Admin, Read-only Admin, Auditor, Admin Owner |
| Export | Export data for the resources and all their child resources | Admin, Read-only Admin, Auditor, Admin Owner |
| Sync | Sync the resources and all their child resources | Admin, Admin Owner |
| Read all settings and request configurations | View settings and request configurations for the resources and all their child resources | Admin, Read-only Admin, Auditor, Admin Owner |
| Edit settings | Edit settings for the resources and all their child resources | Admin, Admin Owner |
| Add and remove tags | Edit tags for the resources and all their child resources | Admin, Admin Owner |
| Edit request configurations | Edit request configurations for the resources and their child resources | Admin, Admin Owner |
| Add, edit, remove users and groups | Edit groups, users, NHIs, and all related resource assignments and their dependencies | Admin, Admin Owner |
| Assign UAR reviewers | Assign users to perform access reviews for the resources | Admin, Auditor, Admin Owner |
| Delete | Delete the resources | Admin, Admin Owner |

### Groups

All group permissions can be scoped to specific groups.

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View groups (overrides visibility groups) | Admin, Read-only Admin, Auditor, Admin Owner |
| View assignments | View all users with access to the groups | Admin, Read-only Admin, Auditor, Admin Owner, Group Leader |
| Export | Export data for the groups | Admin, Read-only Admin, Auditor, Admin Owner |
| Sync | Sync the groups | Admin, Admin Owner |
| Read all settings and request configurations | View settings and request configurations for the groups | Admin, Read-only Admin, Auditor, Admin Owner |
| Edit settings | Edit settings for the groups | Admin, Admin Owner |
| Add and remove tags | Edit tags for the groups | Admin, Admin Owner |
| Edit request configurations | Edit request configurations for the groups | Admin, Admin Owner |
| Add, edit, remove users and groups | Edit groups, users, and NHIs for the groups | Admin, Admin Owner, Group Leader |
| Request on behalf | Request access on behalf of the groups | Admin, Admin Owner, Group Leader, Global Requester |
| Assign UAR reviewers | Assign users to perform access reviews for the groups | Admin, Auditor, Admin Owner |
| Delete | Delete the groups | Admin, Admin Owner |

> [!NOTE]
>
> **Request on behalf** for groups requires version 1.1200 or later. It lets a role—or a service user holding that role—create access requests for a team without being an Opal Admin or a group leader of that team. Requests still go through the normal approval chain, and the permission grants no ability to edit group membership.

### Users

Applies to all users:

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View all users in the Inventory | Admin, Read-only Admin, Auditor, Global Requester |
| Create | Create Opal users | Admin |
| Delete | Delete any users | Admin |
| Export | Export all users | Admin, Read-only Admin, Auditor |
| Reset Opal MFA | Reset Opal MFA for all users in the organization. Not applicable for OIDC or Okta MFA | Admin |

Can be scoped to specific users:

| Permission | Description | Applicable roles |
| - | - | - |
| Edit settings | Edit settings (manager, team when not synced with an IdP) for the users | Admin |
| Add and remove tags | Edit tags for the users | Admin |

> [!NOTE]
>
> Requesting access on behalf of specific *users* is not available on custom roles. It remains limited to Opal Admins and the [Global Requester](https://docs.opal.dev/docs/roles-in-opal.md) role. To let a custom role request for a team, use **Request on behalf** in the groups tab.

### Bundles

Applies to all bundles:

| Permission | Description | Applicable roles |
| - | - | - |
| Create | Create bundles for the organization | Admin |

Can be scoped to specific bundles:

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View bundles (overrides visibility groups) | Admin, Read-only Admin, Auditor, Admin Owner |
| Delete | Delete bundles | Admin, Admin Owner |
| Read all settings and request configurations | View bundle settings | Admin, Read-only Admin, Auditor, Admin Owner |
| Edit settings | Edit bundle settings | Admin, Admin Owner |
| Add, edit, remove groups and resources | Edit all assigned resources and groups for the bundles | Admin, Admin Owner |

### Access reviews

All access review permissions apply to all access reviews.

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View all access reviews, and all the reviewer assignments | Admin, Read-only Admin, Auditor |
| Create | Create access reviews | Admin, Auditor |
| Stop | Stop access reviews | Admin, Auditor |
| Edit settings | Edit access review settings, such as name, deadline, and reminders | Admin, Auditor |
| Send reminders | Send reminders to reviewers for access reviews | Admin, Auditor |
| Export | Export all role assignments for all the access reviews | Admin, Read-only Admin, Auditor |

To assign reviewers, use the **Assign UAR reviewers** permission in the native apps, resources, or groups tabs.

### Access review schedules

Recurring access review schedules on the **Scheduled** tab are managed with the **Access Reviews** permissions above: **Read** to view schedules, **Create** to create schedules and preview scope counts, and **Edit settings** to edit schedule settings. Deleting a schedule requires the **Access Reviews** **Stop** permission.

> [!NOTE]
>
> Triggering an immediate campaign run from a schedule (**Create campaign**) requires the **Access Reviews** **Create** or **Edit settings** permission, and stopping or ending a running campaign requires the **Access Reviews** **Stop** or **Edit settings** permission.

### Owners

All owner permissions apply to all owners.

| Permission | Description | Applicable roles |
| - | - | - |
| Create | Create owners | Admin |
| Add, edit, remove users and groups | Edit the members of owners | Admin |
| Edit settings | Edit owner settings | Admin |
| Delete | Delete owners | Admin |

> [!NOTE]
>
> Owner permissions require version 1.1093 or later. Before that, creating, updating, and deleting owners was restricted to Opal Admins.

### Tags

All tag permissions apply to all tags.

| Permission | Description | Applicable roles |
| - | - | - |
| Read | View tags | Admin, Read-only Admin, Auditor |
| Create | Create tags | Admin |
| Delete | Delete tags | Admin |

> [!NOTE]
>
> Tag permissions require version 1.1190 or later. These permissions govern the tags themselves. To let a role change which tags are applied to an asset, use **Add and remove tags** in the native apps, resources, groups, or users tabs instead.

### Not available on custom roles

The following remain restricted to Opal's reserved roles and cannot be granted through a custom role:

| Capability | Applicable roles |
| - | - |
| View configuration templates | Admin, Read-only Admin |
| Create and delete configuration templates | Admin |
| Edit configuration template settings | Admin |
| Request on behalf of specific users | Admin, Global Requester |
| View Risk Center | Admin, Read-only Admin |
| View events | Admin, Read-only Admin, Admin Owner, Auditor |
| View global settings | Admin, Read-only Admin |
| Edit global settings | Admin |

## Role and visibility hierarchy

Custom roles take precedence over [visibility settings](https://docs.opal.dev/docs/curate-catalog.md#visibility). If a user is assigned a role which gives view access to an asset (resource, group, etc.), but the asset's visibility settings do not include the user's groups, the user can still view the asset.

Note that edit permissions do **not** imply view permissions. If you grant a role the permission to edit a resource, but not permission to view it, permission to view the resource is not included in the role. In that case, the user may be prevented from viewing the resource, depending on visibility settings.

For example:

* Custom Role A has permissions to edit, but **not** view, Resource B.
* Resource B has group visibility settings set to allow Group C to view the group.
* User D and User E are granted access to Custom Role A.
* User D is a member of Group C.
* In this case, User D will be able to view and edit Resource B, but User E will not.

## Inherited permissions

A scoped permission extends downward from the asset you scoped it to:

* A permission scoped to an **app** also applies to every resource and group in that app.
* A permission scoped to a **resource** also applies to that resource's nested resources. If Resource A contains nested Resource B, a permission granted on Resource A also applies to Resource B.

Groups do not inherit permissions from each other—a permission scoped to a group applies to that group only, even if it contains nested groups. To cover every group in an app, scope the permission to the app instead.

## Manage roles via API

To create a scoped role with the API, use [POST /resources](https://docs.opal.dev/api-reference/resources/post-resources.md) with `app_id` set to the Opal connection ID and `resource_type` set to `OPAL_SCOPED_ROLE`.

To set scoped permissions, use `PUT /resources/{resource_id}/scoped-role-permissions`.

To read scoped permissions assigned to a role, use `GET /resources/{resource_id}/scoped-role-permissions`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.