Tutorial: Model exclusive access with RBAC

Use role-based access control (RBAC) to enforce exclusive access to datasets that must stay separate from each other. When each dataset is accessible only through its designated role, users and AI agents must assume that role to access it. To access another dataset, they must switch roles, so a single query can't combine data across use cases, projects, clinical trials, or clients. Combining datasets that must remain separate is sometimes called a toxic join.

Scenario

A researcher works on two clinical trials in one workspace. They need access to both trials, but their work on one trial must not use the other trial's data. You configure a separate role for each trial, test allowed and denied queries, and restrict sharing of workspace assets created as either role.

The researcher remains assigned to the workspace and can enter the workspace as themselves. To require a role for workspace entry, see Tutorial: Require users to assume a role for workspace access.

The example uses two kinds of groups. These are explanatory labels, not formal Azure Databricks terminology:

• Access role: An empty group that holds permissions on a trial's data. You create role-study-1 and role-study-2. Keep them empty. Members inherit a group's permissions, so a member could read the data without assuming a role.
• Member group: trial-researchers, whose members are allowed to assume both access roles. It holds the Assume permission, not permissions on the trial data. A member group is optional. You can also grant the Assume permission directly to individual users or service principals.

The researcher can switch between roles, but each role can read only its own study's table:

In the diagram, the Study 1 group corresponds to role-study-1, and the Study 2 group corresponds to role-study-2.

Prerequisites

• A Unity Catalog-enabled workspace with RBAC enabled. See Enable RBAC.
• Account admin or workspace admin permissions to create roles, grant the Assume permission, and manage workspace assignments. See Who can manage groups?.
• Workspace admin permissions to configure entitlements, compute access, and sharing restrictions.
• An existing test catalog with managed storage, accessible from the workspace. The administrator who creates the data must own the catalog. This tutorial uses trials with new schemas study_1 and study_2. Use a catalog without broad grants that would give the researcher or either role access to both datasets. See Create catalogs.
• A SQL warehouse with Can use granted to the catalog owner who creates the test datasets. The person who grants warehouse access needs workspace admin permissions or Can manage on the warehouse.
• An account group containing the researchers, named trial-researchers in this example. One of its members participates in validation using their own sign-in. This researcher must not be an administrator, catalog owner, or member of a group with broad data access.
• A workspace folder for each role's test notebook. The workspace admin configures access to these folders in Step 3.
• For Step 8, an audit reader configured as described in Verify audit attribution.

Substitute your own catalog, group, and workspace names throughout. Use fictitious test data and new schemas and roles so cleanup does not affect other workloads.

Step 1: Create the test datasets

If either schema already exists, choose a new schema name rather than replacing existing objects.

As the catalog owner, open the SQL editor, select the test warehouse, and run:

CREATE SCHEMA trials.study_1;
CREATE SCHEMA trials.study_2;

CREATE TABLE trials.study_1.patient_info (
  participant_id STRING,
  outcome STRING
) USING DELTA;

CREATE TABLE trials.study_2.patient_info (
  participant_id STRING,
  outcome STRING
) USING DELTA;

INSERT INTO trials.study_1.patient_info VALUES ('study-1-a', 'improved');
INSERT INTO trials.study_2.patient_info VALUES ('study-2-a', 'unchanged');

The participant IDs and outcomes are fictitious. Run both queries to verify that the tables exist and the warehouse can read them:

SELECT * FROM trials.study_1.patient_info LIMIT 100;
SELECT * FROM trials.study_2.patient_info LIMIT 100;

Each query returns its study's single row.

Step 2: Create the access roles and grant the Assume permission

The primary procedure uses account-local groups for the access roles. Account-local groups are useful when creating a group in Azure Databricks is simpler than requesting a new group from Microsoft Entra ID. The member group can be account-local or synced from Microsoft Entra ID, as shown in this diagram:

Create the first empty role using either method:

Account console

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-study-1. Do not add members.
5. Click Confirm.
6. Assign the group to the test workspace with Workspace access and Databricks SQL access. See Assign a group to a workspace.

Workspace admin settings

1. As a workspace admin, log in to the test workspace.
2. Click your username in the top bar and select Settings.
3. Click the Identity and access tab.
4. Next to Groups, click Manage.
5. Click Add Group, then Add new.
6. Enter role-study-1 and select Workspace access and Databricks SQL access. Step 3 explains why this tutorial uses both.
7. Click Add. Do not add members.

This also assigns the group to the workspace and grants you Manage permission on it.

Grant the Assume permission to the researchers

Before assigning the role's data privileges, grant the researchers permission to assume it:

Account console

1. As an account admin, open User management > Groups in the account console and select role-study-1.
2. Click Permissions, then Grant access.
3. Select trial-researchers, select Assume, and click Save.

Workspace admin settings

1. As a workspace admin with Manage permission on the role, open Settings > Identity and access in the test workspace.
2. Next to Groups, click Manage, then select role-study-1.
3. Click Permissions, then Grant access.
4. Select trial-researchers, select Assume, and click Save.

Repeat the steps to create the role and grant the Assume permission for role-study-2. Both roles stay empty. See Choose or create a role for naming guidance and API-based group creation.

Step 3: Configure workspace and compute access

You assigned both roles to the test workspace in Step 2. As the workspace admin, verify that both roles and trial-researchers have both access entitlements, including groups that were already assigned:

• Workspace access: Grants access to core workspace features such as notebooks, jobs, models, and pipelines. This tutorial uses notebooks to verify sharing controls.
• Databricks SQL access: Grants access to Databricks SQL features, including dashboards, queries, and SQL warehouses. This tutorial uses the SQL editor to verify data access.

For all access entitlements and how to manage them, see Access entitlements.

If trial-researchers is not assigned, assign it to the workspace. See Assign a group to a workspace.

Keep the researchers assigned so that they can enter as their user identities and switch back after using a role.

Grant each group access to the SQL warehouse:

1. In the workspace sidebar, click SQL Warehouses.
2. Open the warehouse's Permissions dialog.
3. Add each group with Can use, then save.

Create a separate test folder for each role in a workspace location without broad inherited access. Grant role-study-1 Can Manage on its folder and role-study-2 Can Manage on the other folder. The roles use these folders to create notebooks in Step 7. See Manage workspace objects and Folder ACLs.

Step 4: Grant each role access to its study

As the catalog owner, run:

GRANT USE CATALOG ON CATALOG trials TO `role-study-1`;
GRANT USE SCHEMA ON SCHEMA trials.study_1 TO `role-study-1`;
GRANT SELECT ON TABLE trials.study_1.patient_info TO `role-study-1`;

GRANT USE CATALOG ON CATALOG trials TO `role-study-2`;
GRANT USE SCHEMA ON SCHEMA trials.study_2 TO `role-study-2`;
GRANT SELECT ON TABLE trials.study_2.patient_info TO `role-study-2`;

Do not grant trial-data privileges to trial-researchers. Its members receive the Assume permission instead.

Review direct and inherited access before testing:

• The researcher must have no other grant or group membership that permits reading either table as their user identity.
• No parent group gives either role data access to the other study.
• Check catalog and schema grants as well as table grants. A catalog-level or schema-level SELECT grant applies to current and future child objects and can make both tables accessible. See Privilege inheritance.

Use Catalog Explorer's Permissions tab to inspect grants on the catalog, both schemas, and both tables. See Manage privileges in Unity Catalog. If shared grants prevent this configuration, use an isolated test catalog or workspace. Removing a shared grant can disrupt unrelated users and roles.

Step 5: Restrict sharing of role-owned workspace assets

Without a sharing restriction, a user acting as a role can share workspace assets that the role owns. Configure the restriction for both roles:

1. As the workspace admin, click your username and select Settings.
2. Click Advanced.
3. Find Restrict sharing for groups and click the edit button.
4. Add role-study-1 and role-study-2. Keep any groups already in the list.
5. Click Save.

This restriction applies while acting as a restricted role. It controls sharing of workspace assets that the role owns. It doesn't control privileges on Unity Catalog objects, and it doesn't block every way to copy data. See Workspace asset sharing controls.

Step 6: Verify data access as each identity

One of your researchers completes these checks using their own sign-in:

1. Sign in to the test workspace and verify that your username appears under the workspace name.

2. Open the SQL editor and select the test warehouse.

3. Run each query separately:

   SELECT * FROM trials.study_1.patient_info LIMIT 100;
   SELECT * FROM trials.study_2.patient_info LIMIT 100;
   

   Both queries fail with permission errors.

4. Click the workspace name in the top bar, hover over the current workspace, and select role-study-1 from the role switcher.

5. After the workspace reloads, verify the role name, open the SQL editor, select the same warehouse, and repeat both queries. Only the Study 1 query succeeds.

6. Switch to role-study-2 and repeat the queries. Only the Study 2 query succeeds.

7. Switch back to your username and repeat the checks. Both queries are denied again.

A missing table, an unavailable warehouse, or an authentication error doesn't demonstrate exclusive access. The catalog owner's checks in Step 1 establish that both tables exist. If an unexpected query succeeds, review the grants and memberships from Step 4 before proceeding.

For other ways to assume a role, see Switch RBAC roles. Switching roles in this browser does not change a separately authenticated Databricks CLI profile or connection.

Step 7: Verify workspace asset sharing

The same researcher repeats these checks for each role:

1. Assume the role using the role switcher.
2. In Workspace, right-click the role's test folder and select Create > Notebook.
3. Name the notebook after the study. You do not need to run code in it.
4. Verify that the role owns the new notebook, and then try to share it. Sharing is unavailable while you act as the restricted role, even with Can Manage on the asset.

Use a notebook created while acting as the role, not one owned by the researcher. See Create a notebook and Verify the restriction.

Step 8: Verify audit attribution

As the audit reader, run this query. Replace <workspace-id> with the ID of the test workspace:

SELECT event_time, service_name, action_name,
       identity_metadata.run_by, identity_metadata.run_by_display_name,
       identity_metadata.run_as, identity_metadata.run_as_display_name
FROM system.access.audit
WHERE workspace_id = '<workspace-id>'
  AND identity_metadata.run_as_display_name IN ('role-study-1', 'role-study-2')
  AND event_date >= current_date() - INTERVAL 1 DAY
ORDER BY event_time DESC;

Find the events for the researcher's test queries and notebook creation. identity_metadata.run_by identifies the researcher who initiated each event, and run_as identifies the role used for authorization. The query filters on run_as_display_name, the role's human-readable name. Audit data is updated throughout the day, so a recent event might not appear immediately. See Identity metadata reference.

Optional: Manage the access roles in Microsoft Entra ID

Use this alternative when your organization keeps group lifecycle management in Microsoft Entra ID. Sync an empty access-role group and a member group to Azure Databricks through System for Cross-domain Identity Management (SCIM) provisioning. See Sync users and groups from Microsoft Entra ID using SCIM.

Keep each access role empty in Microsoft Entra ID. Adding members there syncs those memberships to Azure Databricks, where members inherit data privileges without assuming the role.

Start with new Microsoft Entra ID groups

To use new Microsoft Entra ID groups instead of the account-local roles in Step 2, complete these steps:

1. In Microsoft Entra ID, create an empty group for each access role.
2. Identify or create the member group containing the researchers.
3. Sync the access roles and member group to your Azure Databricks account.
4. Grant the member group the Assume permission on each access role using the procedure in Step 2.

Repurpose an existing Microsoft Entra ID group

If a group synced from Microsoft Entra ID already holds the desired data privileges in Azure Databricks, you can keep those grants by repurposing the group as an access role:

1. Create a new member group in Microsoft Entra ID. For example, if the existing group is clinical-trial-1-ds, create clinical-trial-1-ds-members.
2. Move every member of the existing group to the new member group, leaving the existing group empty.
3. Sync both groups to Azure Databricks and verify that the access role has no members.
4. Grant the new member group the Assume permission on the access role. Review other grants or memberships that could still give researchers standing access to the data.

The existing group keeps its data privileges and workspace permissions. You do not need to recreate those grants, but verify that they match the intended study boundary. Plan the membership change with the group's owners because users lose inherited permissions when they move out of the original group.

Complete the workspace configuration and checks

Assign both the access roles and the member group to the workspace and configure entitlements and compute access as in Step 3. To require role assumption for workspace entry instead, see Tutorial: Require users to assume a role for workspace access.

For new access roles, grant data access as in Step 4 and workspace-asset access as in Step 3. For repurposed groups, review the existing grants instead of replacing them.

Verify that the member group has the Assume permission on each access role. All its members can then assume that role.

Configure sharing restrictions and repeat the data, sharing, and audit checks from Steps 5 through 8 using Microsoft Entra ID group names and datasets.

Clean up

For a temporary test, remove only the resources and grants created for this tutorial:

1. As the catalog owner, verify that the two tables contain only the tutorial's test data, then run:

   DROP TABLE trials.study_1.patient_info;
   DROP TABLE trials.study_2.patient_info;
   DROP SCHEMA trials.study_1 RESTRICT;
   DROP SCHEMA trials.study_2 RESTRICT;
   

   The schema drops fail if other objects remain. Do not drop an existing catalog or schema used by other workloads.

2. As the workspace admin, remove the test notebooks and folders. Review any other assets owned by the roles before removing them.

3. Revoke the grants of the Assume permission and resource permissions created for the test, including the catalog and warehouse grants. Remove test-only workspace assignments, preserving the researchers' existing access.

4. Remove the test roles from Restrict sharing for groups, leaving other entries intact.

5. Delete newly created empty roles only after verifying that no workload or asset still uses them. For synced groups, make lifecycle changes in Microsoft Entra ID so synchronization does not recreate deleted groups. Keep existing member groups and their users.

If you repurposed an existing group, plan a separate rollback that restores its original memberships and assignments. Do not use the test-resource cleanup to delete an existing access model.

Next steps