Managing Roles in the UI

The Roles page enables you to find roles, check which groups and users are assigned to them, and view their permissions on data.

Users with specific access can also create, delete, and edit these roles and permissions.

Note: Only catalog admins or users who have been assigned the role ‘okera_policy_management_role' can access the Roles page.

Okera Roles page

Roles

Understanding Roles

Roles enable you to define specific access to data and grant this access to groups.

A role has several components:

  • A role name
  • A list of groups assigned to the role
  • A list of permissions detailing what data these groups can access, and what kind of access they have

Role details pane

You can search for roles by name using the ‘Role name’ filter.

Creating a New Role

Note: Only catalog admins can create roles.

Click the ‘Create new role’ button to create a role:

Create role button

The only requirement for creating a role is to give it a name. Role names may not contain spaces.

Deleting a Role

Note: Only catalog admins can delete roles.

Click the ‘Delete role’ button to delete a role: Delete role button

Note that deleting a role will revoke this role’s access to data.

Permissions

Understanding Permissions

Permissions show what data a role has access to and what type of access they have. A role’s permissions are listed in a table on the role details pane: Permissions table

This table has several columns:

  • Access: The level of privilege being granted by the permission. To learn more, see Privileges.
  • Scope: The granularity of data that the permission grants access to, i.e. catalog, database, table, or column.
  • Data: The exact data that the permission grants access to. Clicking on a database, table, or column will open its details in a new tab.
  • Conditions: Any ABAC restrictions that have been applied to this permission, e.g. excluding certain tagged data from access. To learn more, see ABAC.

Some tables may also have a column named ‘Conflicts’. Read more about this in the 'Handling Permission Conflicts' section.

URI Grants

If a role has been granted any URI grants, they will appear in a tab next to Permissions: URI tab

To learn more about URI’s, see Privileges.

Adding a New Permission

Note: Only catalog admins and users with the ability to grant on at least one data object can add permissions to roles.

Click the ‘+’ icon next to the Permissions header to add a permission to a role:

Add a permission

This will launch a dialog that prompts you to provide several pieces of information about your new permission:

Create permission dialog

  • Access Level: Select the degree of access you would like to grant to this role. The level you select may affect what options are available in the dialog. To learn more, see Privileges.
  • Database/Dataset: Select the database or dataset that you want to grant access to. The selection menu is limited to databases and datasets that you have ‘grant’ ability on.
  • Tags: Optionally select tags if you wish to either limit access to only certain tagged data, or restrict users from accessing certain tagged data. Read more in the 'Limiting Access with Tags' section below.

As you fill out these fields, the policy summary will update to show you a preview of your permission in both natural language and SQL. Use the toggle in the top right corner of the summary to switch between views:

Policy summary toggle

Once you’ve filled out all required fields and confirmed that your permission looks correct in the policy summary, click ‘Add permission’ to grant this new access to the role.

Limiting Access with Tags

Both tag fields in the dialog are optional but can further clarify what type of data a role should have access to.

If you want to allow access to only a specific type of data, select the relevant tags from the ‘Grant to all data tagged as...’ dropdown:

Select tags to include

Selecting a tag from this dropdown will only allow the role access to columns in your selected database or dataset that have this tag. In the example above, a role would only have access to columns tagged as ‘region: west’ within the dataset.

If you want to instead prevent the role from accessing a specific type of data, select the relevant tags from the ‘Except for data tagged as…’ dropdown:

Select tags to exclude

Selecting a tag from this dropdown will not allow the role to access any columns in your selected database or dataset that have this tag. In the example above, a role would have access to everything in the dataset, except for columns tagged as ‘pii: credit_card’.

If you select multiple tags from either of the tag dropdowns, you must specify whether access is limited to any of these tags (an ‘OR’ statement) or all of these tags (an ‘AND’ statement):

All or any tags

See Managing Tags for more information about creating and assigning tags to data.

Handling Permission Conflicts

Sometimes creating a new permission will result in a conflict warning, as shown here:

Conflict error

You may also see permission conflicts indicated with a red error icon on existing roles:

Conflict on role

Conflicts here mean that there are two or more permissions on the same role that contradict each other or are redundant. The two reasons that a conflict can occur are:

  • Overlapping scope: Two or more permissions are affecting the same data but at different scopes, e.g. one permission grants access to a database, and another permission grants the same access to a table within that database.
  • Conflicting conditions: Two or more permissions are affecting the same data but have different tag-based conditions.

If you attempt to create a new permission and get a conflict warning, you may still create the conflicting permission but this role will be flagged as having conflicts.

When a role has conflicting permissions, the Conflicts column will appear in the Permissions table. Within this column, you can click ‘View Conflicts’ to see conflict details for a given permission. You must delete conflicting permissions to resolve these conflicts.

Deleting Permissions

Note: Only catalog admins and users with the ability to grant on the relevant data objects can delete permissions.

Click the ‘Delete’ icon at the end of a permission’s row to delete it:

Delete permission button

This will revoke any access granted by this permission from the role.

Groups, Users, and Data

Adding and Removing Groups

Note: Only catalog admins can add and remove groups from roles.

Use the ‘+’ and ‘-’ buttons next to the Groups list to add and remove groups respectively:

Add or remove groups

Ensure that you spell group names correctly when adding as there are currently no checks in place to prevent misspelled group names.

Filtering by Group and User

In addition to searching for roles by name, you may also filter by group and user.

Filtering by group will show you all roles assigned to that group:

Filter by group

Filtering by user will show you all roles assigned to groups containing that user (i.e. all roles that apply to this user):

Filter by user

Groups that contain the user you have filtered on will be indicated in bold pink text as shown in the image above.

Checking Access to Data

You can additionally use the right-hand section of the filter bar to check which roles have access to specific data:

Check access to data

If you select a dataset from this filter, the Roles page will display…

  • All roles with permissions on this dataset
  • All roles with permissions on the database containing this dataset
  • All roles with catalog-level permissions, as they have access to all data

If you select a database from this filter, the Roles page will display…

  • All roles with permissions on this database
  • All roles with permissions on datasets within this database
  • All roles with catalog-level permissions, as they have access to all data

If you select the ‘Catalog only’ checkbox, the Roles page will display…

  • Only roles with catalog-level permissions

You can also check which roles have permissions on a given dataset from the Datasets page using the Roles button: Go to roles

Clicking this button will open the Roles page in a new tab and will pre-populate the filters with your dataset in order to only display roles with access to this dataset.