Skip to main content
Last updated on

Tutorial: Require users to assume a role for workspace access

Use role-based access control (RBAC) to require selected users to assume a role when accessing a Databricks workspace. Their workspace sessions use the role's permissions, which keeps access scoped to a particular project or task. Other users assigned to the same workspace can continue to access it as their user identity.

Scenario​

The members of trial-researchers work on a clinical trial in the trials workspace. They also belong to groups that grant access to other projects. Their user identities inherit permissions from those groups and from the groups' parent groups.

You create role-trial-researcher with access to the trial_data catalog and grant trial-researchers permission to assume it. You assign the role to the workspace. The researchers then enter the workspace as the role, whose permissions replace their user-identity permissions for that session. See When you must assume a role to enter a workspace for the general entry behavior.

Prerequisites​

  • A Unity Catalog-enabled workspace with RBAC enabled. See Enable RBAC.
  • Account admin or workspace admin permissions to create the role, grant the Assume permission, and manage workspace assignments. See Who can manage groups?.
  • Ownership of, or MANAGE on, the catalog the role needs to read.
  • Workspace admin permissions or Can manage on the SQL warehouse used in the example.
  • An account group containing the researchers, an existing table to query, and a SQL warehouse. This tutorial uses trial-researchers, trial_data.research.observations, and the trials workspace. Substitute your own names throughout.
  • The users in trial-researchers exist in your Databricks account but are not assigned to the trials workspace, either directly or through group membership, including nested groups.
  • A researcher from trial-researchers and another user who remains assigned to trials, both available to validate access using their own sign-ins.
  • An audit reader with access to system.access.audit to verify the researcher's activity under the role. See Verify audit attribution.

If your researchers already have workspace access, see the instructions for removing direct user assignments and group assignments. Removing a group's assignment also affects its other members.

Step 1: Create the role​

For this tutorial, create an empty account group to serve as the 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 role-trial-researcher. Do not add members.
  5. Click Confirm.
  6. Assign the group to trials with Workspace access and Databricks SQL access. See Assign a group to a workspace.

Keep this group empty. Members of a group assigned to a workspace inherit its workspace assignment and can enter as themselves. In the next step, you grant researchers the Assume permission instead of membership.

The role is assigned to trials with Workspace access and Databricks SQL access, so researchers can use the SQL editor and core workspace features while acting as the role. For what each entitlement grants, see Access entitlements. You configure data privileges and SQL warehouse permissions separately in Step 3.

Step 2: Grant researchers permission to assume the role​

Grant the Assume permission to trial-researchers. If you use workspace admin settings, you must have Manage permission on role-trial-researcher.

  1. As an account admin, open User management in the account console.
  2. On the Groups tab, click role-trial-researcher.
  3. Click the Permissions tab, then click Grant access.
  4. Search for and select trial-researchers, select Assume, and click Save.

The researchers now have the Assume permission without inheriting the role's permissions as their user identities.

Step 3: Grant the role access to the trial data​

As the catalog owner or a user with MANAGE on trial_data, run this statement in a notebook or the SQL editor:

SQL
GRANT USE CATALOG, USE SCHEMA, SELECT ON CATALOG trial_data TO `role-trial-researcher`;

These catalog-level grants allow the role to read all current and future tables and views in trial_data. For narrower access, replace the catalog-level grant with USE CATALOG on trial_data, USE SCHEMA on the required schema, and SELECT on specific tables. See Privilege inheritance.

As a workspace admin or a user with Can manage on the SQL warehouse, grant the role access to the warehouse:

  1. In the workspace sidebar, click SQL Warehouses.
  2. Click the Kebab menu icon. kebab menu next to the warehouse, then click Permissions.
  3. Add role-trial-researcher with Can use.

The role also inherits permissions from its parent groups. By default, it inherits permissions granted to the workspace's users system group and the account's account users system group. Changing a shared grant affects other users and roles that inherit it. See How role permissions apply.

Step 4: Enter the workspace as a researcher​

One researcher completes these steps using their own sign-in:

  1. Open the trials workspace and log in. If role-trial-researcher is the only role you can assume there, you enter as that role automatically.
  2. If you can assume multiple roles, select role-trial-researcher from the Assume role drop-down menu on the You must assume a role to access this workspace page, then click Continue. The menu lists the roles you can assume in trials.
  3. Verify that role-trial-researcher appears under the workspace name in the top bar.

Step 5: Verify the results​

The same researcher continues with these checks:

  1. Open the role switcher by clicking the workspace name in the top bar and hovering over the current workspace. Your user identity is unavailable, so you cannot switch to it. You can switch to another role that you have permission to assume in trials.

  2. Open the SQL editor, select the warehouse granted in Step 3, and run:

    SQL
    SELECT * FROM trial_data.research.observations LIMIT 10;

    The query succeeds using the role's permissions.

Another user who remains assigned to trials signs in using their own account and verifies that they can enter as their user identity.

The audit reader inspects the researcher's query event in system.access.audit: identity_metadata.run_as identifies the authorizing role and run_by identifies the researcher who initiated the request. The corresponding run_as_display_name and run_by_display_name fields contain their human-readable names. Audit data is updated throughout the day, so a recent event might not appear immediately.

Optional: Access the workspace programmatically​

A researcher who has no workspace assignment must also assume a role when authenticating with the Databricks CLI. The participating researcher installs the Databricks CLI as described in Install or update the Databricks CLI, then logs in using their own sign-in and a named profile:

Bash
databricks auth login --host <workspace-url> --profile trial-researcher

The researcher selects role-trial-researcher under Authorize as.. in the browser and clicks Continue. They use --profile trial-researcher with subsequent commands. See Databricks CLI.

Clean up​

The administrators who configured the role, data privileges, and warehouse access remove the grants and assignments they created for this tutorial:

  1. Remove the tutorial's grant of the Assume permission and the role's workspace assignment. Keep any grants or assignments used by other workloads.
  2. Remove the role's trial_data and warehouse grants created for this tutorial. Review assets owned by the role before deleting it.

Next steps​

On this page