Skip to main content
Last updated on

Get started with RBAC

Set up role-based access control (RBAC) in Databricks so users and Databricks service principals can assume roles with the permissions they need for each task. Choose a group to use as a role, grant permission to assume it, and configure its access. For the permission model, see Role-based access control (RBAC).

Requirements​

  • A workspace enabled for identity federation. See Identity federation.
  • RBAC enabled at the account and workspace levels. An account admin and a workspace admin perform the respective enablement steps.
  • Account admin or workspace admin permissions to create groups and assign them to workspaces.
  • Manage permission on the role's group to grant or revoke the Assume permission. Account admins have Manage on all groups. Workspace admins receive Manage on groups they create. See Who can manage groups?.
  • Workspace admin permissions to manage an existing group's workspace entitlements.
  • Permission to grant access to the data, compute, and workspace assets the role needs. The required permissions depend on the resources you choose.

Different administrators can perform these tasks. Group managers can manage group permissions through the API. See Manage permissions on a group.

Enable RBAC​

RBAC is already enabled for most customers. If you are not sure whether it is enabled for your account and workspaces, check these settings:

  1. As an account admin, ensure Role-based access control (RBAC) account-level enablement is enabled on the account Previews page.
  2. As a workspace admin, ensure Role-based access control (RBAC) is enabled on the workspace Previews page.

The account setting makes the workspace setting available. Enable RBAC in each workspace where users need to assume roles.

Choose or create a role​

In Databricks, a role is implemented as an account group. You can use a group created in Databricks or an external group from your identity provider. External groups are also account groups. For group sources and how account groups differ from workspace-local groups, see Group sources.

Decide whether the group should have members:

  • Members inherit the group's permissions, including permissions from its parent groups, as part of their own identity. Members can assume the group as a role to limit a session to the group's permissions and collaborate on assets owned by the group.
  • You can grant the Assume permission directly to non-members without adding them as members, so they don't inherit the group's permissions as their own identity. For a pattern that requires deliberate role assumption to access data, use an empty group and keep it empty. See Tutorial: Model exclusive access with RBAC.

To create an account-local role:

  1. As an account admin, log in to the account console.
  2. In the sidebar, click User management.
  3. On the Groups tab, click Add group.
  4. Enter a name for the role, then click Confirm.
  5. Add members only if they should also inherit the group's permissions as their own identities.

Databricks recommends using a consistent prefix, such as role-, to distinguish groups used as roles. For example, use role-study-1 for a role and trial-researchers for a group whose members can assume it.

For group synchronization procedures, see Manage Databricks groups.

Optional: Use the Account Groups API​

You can also create and manage groups using the Account Groups API. For endpoints and examples, see Manage groups using the API.

Manage the Assume permission​

Users and Databricks service principals can assume a role when they have the Assume permission, either directly or through group membership. Grant the permission on the group that implements the role. Group members have the Assume permission automatically, so you only need explicit grants for non-members.

To grant the Assume permission, use either the account console or workspace admin settings:

  1. As an account admin, open User management > Groups and select the role's group.
  2. Click Permissions, then Grant access.
  3. Select the user, Databricks service principal, or account group that should be able to assume the role.
  4. Select Assume, then click Save.

When you grant the Assume permission to a group, its members can assume the role. They do not need to be members of the role itself. You can also grant the Assume permission directly to individual users or Databricks service principals.

To revoke the Assume permission, remove the applicable grant. Check whether the principal can still assume the role through membership in the role or another group granted the Assume permission. Removing a direct grant does not remove those other paths.

Limit Manage on the role to the administrators responsible for its membership and permissions. A principal with Manage can grant the Assume permission to others. See Manage permissions on a group for the account-console and workspace-admin procedures, or Grant or revoke the Assume permission on a group for the Access Control API.

Configure workspace access​

Assign the role to each workspace where it should be available. Account admins and workspace admins can assign groups to workspaces. See Assign a group to a workspace.

Each access entitlement grants access to a specific set of features in the workspace. Select the entitlements the role needs:

  • Workspace access: Grants access to core workspace features such as notebooks and jobs.
  • Databricks SQL access: Grants access to Databricks SQL features, including dashboards, queries, and SQL warehouses.

See Access entitlements for all access entitlements, including Consumer access, and how to manage them. Select the role's entitlements explicitly instead of relying on the workspace's default entitlements. See Overview.

Decide whether users should also be assigned to the workspace as their own identities:

  • Users with a direct or inherited workspace assignment and an access entitlement can enter as themselves and switch to a role they have permission to assume.
  • Users without a direct or inherited workspace assignment must assume a role assigned to that workspace to enter. They need the Assume permission on the role, and the role needs an access entitlement. See Tutorial: Require users to assume a role for workspace access.

The Assume permission controls who can use the role. Workspace assignments control where it is available, and access entitlements control which workspace features it can use. Grant data privileges and permissions on compute and workspace objects separately.

Grant access to resources​

Grant the role the permissions needed for its task:

  • Data: Grant Unity Catalog privileges using SQL or Catalog Explorer. Reading a table requires USE CATALOG on its catalog, USE SCHEMA on its schema, and SELECT on the table. Privileges such as SELECT granted on a catalog or schema also apply to its current and future child objects. See Privilege inheritance and Manage privileges in Unity Catalog.
  • Compute: Grant permission to use the chosen compute resource. For a SQL warehouse, grant Can use to allow the role to run queries. See Manage a SQL warehouse. For dedicated compute assigned to a group, see Dedicated compute group access.
  • Workspace objects: Use access control lists (ACLs) to grant access to notebooks, jobs, and other workspace objects. See Access control lists.

Roles inherit permissions from their parent groups. By default, your roles also inherit permissions granted to the workspace's users system group and the account's account users system group. Changing shared grants affects other users and roles that inherit them. See How role permissions apply.

If users acting as the role must not share workspace assets that the role owns, configure workspace asset sharing controls.

Use and verify the role​

A user or Databricks service principal with the Assume permission authenticates as the role using a method in Switch RBAC roles. Check that the role can access the required resources and receives permission errors for resources outside its intended access. Compare those results with the same identity acting without the role.

For data governed by attribute-based access control (ABAC), policies evaluate the active role. See Use RBAC with ABAC for identity-function behavior and combined-use patterns.

Verify audit attribution​

Query system.access.audit from a Unity Catalog-enabled workspace in the same account and cloud region as the workspace where you tested the role. The audit reader needs USE CATALOG on system, USE SCHEMA on system.access, SELECT on system.access.audit, and permission to use the query compute. See Grant access to system tables.

The identity metadata fields distinguish the identities involved in an event:

  • run_by: the identity that initiated the event.
  • run_as: the identity used for authorization.
  • run_by_display_name and run_as_display_name: the corresponding human-readable names.

For interactive requests made while assuming a role, run_by identifies the user and run_as identifies the role. For job workloads, run_by identifies the Jobs service's application Databricks service principal. See Set Run as to a group.

Filter by workspace_id and event_date to locate your test activity. Audit system table data is updated throughout the day and does not support real-time monitoring. If a recent event is missing, check again later. See Audit log system table reference and System tables reference.

Additional resources​

Choose a tutorial for a complete setup and verification procedure:

Before applying a role to other workloads, review Role-based access control (RBAC) limitations.

On this page