Skip to main content


Scuba Docs

Manage users and roles with RBAC

Role-based access control (RBAC) is a method of regulating access to a computer, network, or application by assigning permissions to users based on a role. Individual users are grouped into roles based on job responsibilities, and system access is assigned based on role.

RBAC provides the ability to segregate duties within a team. This allows you to grant only the level of access a user requires to perform their job, instead of giving everybody unrestricted permissions.

You can map your organization's SAML groups to logical roles within Scuba using the Scuba UI.

RBAC is enabled by default, and a user must be a member of a role before they can view or edit any objects in Scuba. By default, new user-created objects are not visible to other users until they're shared.

How to configure RBAC

To create roles from provided SAML groups, you must have SAML single sign on. To manually assign users to roles without using SAML groups, contact your Technical Account Manager.

Prepare to set up RBAC

In preparing to set up RBAC, decide how you will map your SAML groups to roles in Scuba. Then decide what sharing privileges each role will have.

For example, SAML might have sales, finance, engineering, product marketing, web marketing, and marketing analytics groups. You might decide to create an Scuba role that corresponds to each group. Or you might decide to map multiple groups to one role. For example, you could make an Scuba role called "marketing" out of the product marketing, web marketing, and marketing analytics SAML groups. Then you might decide that the finance role can share its objects only with the finance role, while the marketing role can share with marketing, engineering, sales, and finance.

By default, Scuba includes the following roles:

  • The user role. Someone in this role can log into Scuba, see datasets and objects for which they have permission, and run queries. They can also create and save personal boards and knowledge objects, such as actor, event, and flow properties.

    It is recommended that an ia_admin set the new_default_object_permissions application setting to query for the user role. This grants all user role users query permission on all new objects. This lets the user role users share with each other any object, including a query, that references another flow, property, or measure. Without this setting enabled, a user sharing a query must grant access to each top-level object referenced in the query.

  • Four admin capability bundles that you can optionally assign to a role. See About administrator roles below.

Configure Scuba RBAC

Once you have planned your mappings and sharing privileges, create each new role using the Scuba UI. To create a new role:

  1. Click the Admin gear icon. At the top of the page, click the Role management icon.
  2. At the top right, click +New role.
  3. At the top of the role management page, type a name for your new role.
  4. Assign one or more SAML groups to each new role by adding them to the Member groups field. You can do this one of two ways:
    • Coordinate with your technical account manager to add SAML groups to your Scuba system. Once the group names are in Scuba, you can use the dropdown in the Member groups field to choose from SAML groups that are already recognized. Click +add group then select from the dropdown.
    • You can (carefully!) type SAML group names into the UI. Click +add group then type the SAML group name. The SAML group name displays red until you click Save at the top right of the page. After you save it, the group name is available in the Member groups dropdown. This method is sensitive to case, special characters, and any typos. Saving does not validate the name against your SAML.
  5. Set sharing permissions for the role.

    When migrating from 3.x, you must edit the User role so that it has a share permission and can share with other users. That is, Admin > Role Management > User > Can share with roles must include User.

  6. Set dataset access for the role in the Can access datasets field.
  7. (Optional) Assign an admin capability bundle to the role. See About administrator roles below for more information.
  8. Click Save at the top right.

Assign role permissions from the CLI

A user_admin can manage roles from the CLI.

To see a summary table of the role information, type the following:

mysql> select * from role;
| id | customer_id | name  | is_admin |
|  1 |           1 | admin |        1 |
|  2 |           1 | user  |        0 |

To assign query permissions by default on all new objects for the user role (roleID 2 in this example), type the following:

ia settings update query_api new_object_default_permissions '{"role2": "query"}'

For more information about the CLI, see:

Best practice: Separate data access roles from capability roles

It is a good idea to create a set of groups in your authentication provider that are defined by what data they can access, and another set of groups that are defined by the capabilities they have. Then build these two sets of groups into a set of meaningful roles.

If I change group membership in my SAML, how does it show up in Scuba?

Every time a user logs into Scuba, their authentication provider passes the list of SAML groups that user is a member of. Scuba determines which role to assign the user based on the SAML group membership. 

If a user logs in with a group that is not mapped to any role, they are put in the User role for that login session.

About capabilities

The following table lists the capabilities that you can assign to a role. Sharing with roles and dataset access are granted by the administrator in the role definition, in the UI at Admin > Role management. Access to specific knowledge objects like boards, flows, and custom (manual) properties are granted on a per-object basis. 

Capability Detail How to configure
Can share with roles A list of other roles that a user assigned to the current role can share an object with. The user can share with either the entire role, or with any user assigned to that role. User admin configures in role definition.
Can access datasets You can restrict dataset or table access by role. User admin configures in role definition.
Read access on an object A user or role with read access on an object can view the object. The user or role cannot edit the object, but they can share the object with more users or roles. User or admin configures per object, through Share workflow.
Write access on an object A user or role with write access on an object can view and edit the object and its definition, and share the object with more users and roles (if the roles are listed in Role definition under Can share with). User or admin configures per object, through Share workflow.
Query access on an object A user or role with query access on an object (such as an actor property or flow) can view the results of a query that uses the object in the query definition but cannot grant access to additional users. An object that you have only query access to does not appear in your typeaheads, dropdowns, or in the lists of objects in the Data section of the UI. User or admin shares a top-level query or flow using the Share workflow. Dependent objects are shared implicitly with query permission.

About administrator roles

Administrator roles are bundles of capabilities that you can add to a role in the Scuba UI. A user admin can add an administrator role to an existing role as follows:

  1. Navigate to Admin > Role management.
  2. Select the role you wish to add admin capabilities to.
  3. At the bottom left, select the check box for the appropriate admin role or roles. Selecting multiple check boxes grants the union of the capability bundles.

The following table describes the available administrator roles and the corresponding bundled capabilities.

Admin role Capabilities
UX admin role Has read and write access to Admin menu in UI. Can see all users' objects. Can edit titles of raw event properties. Can create a banner or a cluster info page. Has read-only CLI access to commands, but not to cluster settings.
User admin role Can create and manage users and email domains in the CLI. Has read-only access to Admin menu in the UI.
Import admin role Can create, list, or export tables, pipelines, and jobs with the CLI for importing data into Scuba. Can delete pipelines and jobs. Cannot access the Admin menu in the UI.
Delete admin role Same as Import admin; can also delete data and time ranges. Can also CRUD tables and columns. Cannot access the Admin menu in the UI.


The following table describes the sets of CLI commands available to each admin permissions bundle:

CLI functionality












create, list, export

create, list, export, delete-time-range, delete


























Next steps

Now that you've created user roles, your users can:

  • Was this article helpful?