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.
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
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:
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:
Note that deleting a role will revoke this role’s access to data.
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:
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.
If a role has been granted any URI grants, they will appear in a tab next to Permissions:
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:
This will launch a dialog that prompts you to provide several pieces of information about your new permission:
- 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:
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:
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:
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):
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:
You may also see permission conflicts indicated with a red error icon on existing roles:
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.
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:
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:
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:
Filtering by user will show you all roles assigned to groups containing that user (i.e. all roles that apply to this 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:
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:
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.