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 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. 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 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.

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.

4. Set the role’s name, description, and admin, then optionally update 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.

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>.

​

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 for examples of how roles interact with existing settings, and 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, and applies only to the groups they lead.

​

Native apps

Applies to all apps: Can be scoped to specific apps:

​

Resources

All resource permissions can be scoped to specific resources.

​

Groups

All group permissions can be scoped to specific groups.

​

Users

Applies to all users: Can be scoped to specific users:

​

Bundles

Applies to all bundles: Can be scoped to specific bundles:

​

Access reviews

All access review permissions apply to all access reviews. To assign reviewers, use the Assign UAR reviewers permission in the native apps, resources, or groups tabs. Access review schedules do not have their own permissions. The Read, Create, and Edit settings permissions above also cover the corresponding actions on schedules; deleting a schedule remains limited to Opal Admins and Auditors.

​

Owners

All owner permissions apply to all owners.

​

Tags

All tag permissions apply to all tags.

​

Not available on custom roles

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

​

Role and visibility hierarchy

Custom roles take precedence over visibility settings. 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 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.