Roles#

Roles control who can do what in Starburst access control. A role bundles privileges together, so you grant privileges to roles and assign roles to users instead of granting privileges to each user. A role has a name and an optional description. A role name can have 1 to 64 characters, and it can contain only lowercase letters, numbers, and underscores.

At any moment, a user acts under one role, called the current role. Starburst access control includes two predefined roles, accountadmin and public.

You can also manage roles with the Control Plane API.

Predefined roles#

Starburst access control includes the following predefined roles. You can’t edit or delete them.

  • accountadmin: This role has the Manage security privilege, so it can grant any privilege to any role, including itself. It also has the other account privileges by default. Any role with Manage security can give itself full access in the same way. Assign this role only to a small number of trusted administrators.

  • public: Every user and every role holds this role. Any privilege that you grant to this role applies to all roles at all times.

Active role set#

The active role set is your current role plus all roles that are granted to it, directly or through other roles. The privileges, policies, and ownership of every role in the active role set apply to your queries and actions. A DENY from any of these roles overrides an allow.

For example, if the reader role is granted to the analyst role, and your current role is analyst, your active role set is analyst, reader, and public. If your current role is reader, your active role set doesn’t include analyst.

Plan your roles#

Create roles that match the groups of people who use your data, and grant each role only the privileges that those people need. Most users only query data, so a role such as data_consumer with Select from table on the data that they use is often enough.

For administration, split the work across roles instead of granting accountadmin widely. For example:

  • data_admin owns the catalogs and clusters, and has the Create catalog and Create cluster privileges.

  • security_admin owns the custom roles, and has the Create role privilege.

Current role and default role#

The privileges that apply to a query are the privileges of the roles in the user’s active role set. By default, the current role is the user’s default role. If a user has no default role, their current role is public.

You can switch to any role that you hold directly or through the role hierarchy, including public. In the Control Plane UI, use the profile menu. In other SQL clients, run SET ROLE <role>. SET ROLE ALL and SET ROLE NONE aren’t supported.

Grant a role#

When you grant a role to a user, the user can act under that role. Granting a role to a user is the same as assigning the user to the role.

When you grant a role to another role, you build a role hierarchy. The role that receives the grant gets the privileges and ownership of the granted role. A DENY on the granted role overrides an allow on the receiving role. You can’t grant a role to itself.

To grant a role, your current role must own the role, hold it with the admin option, or have the Manage security privilege.

To grant a role in SQL, use GRANT. Add WITH ADMIN OPTION to let the receiving role grant the role to other roles:

GRANT support_admin TO ROLE sales_admin;
GRANT support_admin TO ROLE sales_admin WITH ADMIN OPTION;
GRANT support_admin TO USER alice;

You can’t use WITH ADMIN OPTION when you grant a role to a user, because only roles can grant roles.

Owned entities#

Roles can own entities, such as catalogs, tables, and clusters. The Owned entities tab of a role lists the entities that the role owns, with their kind, owning role, and creation and modification dates. To filter the list, enter a name or select an Entity kind, and click Apply. To see only the entities that the role owns directly, turn on Only directly owned entities. For more information, see Ownership.

Manage roles in the UI#

Create a role#

  1. Go to Access > Roles and privileges.

  2. Click Add role.

  3. Enter a name and, optionally, a description.

  4. To let your current role hold the new role, select Grant to the creating role?. Your current role then gets the new role’s privileges, policies, row filters, and column masks.

  5. Click Add role.

To edit a role, open the role’s menu in the roles list and select Edit role.

Assign a user to a role#

  1. Go to Access > Roles and privileges, and select the role.

  2. On the Users tab, click Assign user.

  3. Select the user and click Assign user.

To remove a user from the role, click Unassign next to the user.

Assign a role to another role#

  1. Go to Access > Roles and privileges, and select the role that receives the grant.

  2. On the Roles tab, click Assign role.

  3. Select the role in Role to assign. To let the receiving role assign the role to other roles, turn on Allow role receiving privilege to grant to others.

  4. Click Assign role.

To remove the role, click Revoke next to it.

Set a user’s default role#

  1. Go to Access > Users.

  2. In the user’s row, open the menu and select Edit user.

  3. Select the role and turn on Make this the default role. Roles that are assigned to the user appear on the Your roles tab. Roles that the user inherits, such as public, appear on the Inherited tab.

Delete a role#

  1. Go to Access > Roles and privileges.

  2. In the role’s row, open the menu and select Delete role.

  3. Confirm that you want to delete the role.

If Starburst access control can’t delete the role, the confirmation dialog shows an error. For example, you can’t delete a role that has policies or that owns entities. Delete the policies or change the owner of the entities first. You can’t delete the predefined roles.