Switch RBAC roles

You can assume a role with role-based access control (RBAC) in Azure Databricks in several ways. The role's permissions apply to the requests or compute operations performed as that role. The scope depends on the method: switching roles in the workspace changes the browser session, while authenticating a Databricks CLI profile or connecting to group compute affects that profile or compute session.

Requirements

To assume a role, you must have the Assume permission on it. You can receive the Assume permission directly, through a group granted the Assume permission, or through membership in the group that implements the role. The role must be assigned to the workspace with the access entitlements it needs. See Configure workspace access.

Important

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 a shared grant affects other users and roles that inherit it. See How role permissions apply. Access entitlements are configured separately. See Configure workspace access.

Role switcher in the workspace

Use the role switcher to assume a role across the entire workspace. All access, permissions, ownership, and actions are as the role for the duration of the session.

1. In the Azure Databricks workspace, click the workspace name in the upper right corner of the top bar.
2. Hover over the current workspace (the top item in the menu) to reveal the role switcher submenu.
3. In the submenu, click the role you want to assume.

The UI reloads and the identity shown under the workspace name changes to the role you selected.

To switch back to your user identity, open the same submenu and select your username. If you entered the workspace by assuming a role because you aren't assigned to the workspace, your username isn't available to select. See When you must assume a role to enter a workspace.

Note

If you do not see the role switcher submenu, verify that you are a member of a group assigned to the workspace, or that you have been granted the Assume permission on a group assigned to the workspace. See Manage permissions on a group.

When you must assume a role to enter a workspace

If you aren't assigned to a workspace, either directly or through group membership, but you have the Assume permission on a group that is assigned to the workspace, you must assume a role to enter the workspace. This depends on your own workspace assignment, not on a workspace setting, so other users who are assigned to the same workspace still enter as themselves.

For setup instructions and the role-entry experience, see Tutorial: Require users to assume a role for workspace access.

Workspace URL (deep link)

You can assume a role directly from the workspace URL by adding the aid (assume ID) query parameter set to the group's ID: aid=<group-id>. Opening that URL authenticates you as your user identity as usual, then automatically assumes the role, so you don't need to use the role switcher.

For example, to open a workspace already acting as a role:

https://<workspace-url>/?o=<workspace-id>&aid=<group-id>

This is useful for bookmarking or sharing a link that lands directly in a role. Azure Databricks keeps the aid parameter as you navigate within the workspace, so you remain in the role for the session. Switching to a different workspace clears it. The role is an account group and must be assigned to each workspace where you use it.

To retrieve a group's ID, use the Account Groups API. To switch roles or return to your user identity after opening the link, use the role switcher.

Dedicated compute assigned to a group

When you connect to a dedicated compute resource assigned to a group, operations that use the compute's assigned principal use that group's permissions. You do not need to switch roles in the workspace UI first.

The workspace must be enabled for Unity Catalog, and the compute must use Databricks Runtime 15.4 or above. The group also needs access to the notebooks and other resources used on the compute. Operations handled by the notebook environment, such as %run, use the user's permissions rather than the group's permissions. See Dedicated compute group access for setup and limitations.

Databricks CLI

When you use OAuth user-to-machine (U2M) authentication with the Databricks CLI, it opens your web browser to complete the authentication flow. If you have the Assume permission on one or more roles, you choose in the browser whether to authenticate as your own user identity or as one of those roles. If you aren't assigned to the workspace, you can't authenticate as your own identity and must select a role. See When you must assume a role to enter a workspace. Install the Databricks CLI before you start. See Install or update the Databricks CLI. To start the login flow, run:

databricks auth login --host <workspace-url> --profile <profile-name>

After you complete the login flow, the Databricks CLI saves a configuration profile and manages short-lived OAuth tokens for it. Commands using this profile run as the role you selected. Switching roles in the workspace UI does not change this profile's identity. For example:

databricks warehouses list --profile <profile-name>

For details on Databricks CLI authentication, see Authentication for the Databricks CLI.

API (OAuth access tokens)

You can generate a workspace-level OAuth access token to make API calls as a role. The token's OAuth scopes limit which APIs it can call, and the role's permissions determine its access to resources.

To generate a role-scoped token, run databricks auth login as described in Databricks CLI and select the role in your web browser. Retrieve an access token for the profile:

databricks auth token --profile <profile-name>

Use the response's access_token in the API request's Authorization: Bearer header. A token copied to another application does not refresh itself. See databricks auth token.

For a manual U2M flow, add assume_group=<group-id> to the workspace authorization URL. See Generate a workspace-level authorization code.

For an unattended process using a service principal, include assume_group=<group-id> in the machine-to-machine (M2M) workspace token request. Both the service principal and the role must be assigned to the workspace. Account-level token requests do not support role assumption. See Assume a role and Tutorial: Scope an AI agent's access with RBAC.

Third-party BI tools

Third-party BI tools that support OAuth (such as Tableau and Power BI) can authorize as a role. After authorization, queries sent through that connection use the role's permissions. The role needs permission to use the selected compute and access the queried data. Follow the tool's supported authentication and compute configuration. See Databricks ODBC and JDBC Drivers.

For known issues that affect BI tools and drivers when acting as a role, see Known issues.

What changes when you assume a role

When you use the workspace role switcher:

• Notebooks and queries: Run as the role. The role's permissions govern interactive queries and Unity Catalog operations performed as that role.
• Jobs: When you create a job while acting as the role, the job's Run as setting is the role. You can also set a job's Run as to a group without assuming it first. See Set Run as to a group.
• Workspace assets: The role owns any assets you create (notebooks, SQL queries, SQL warehouses, jobs).
• Audit logs: Distinguish the identity that initiated an event (identity_metadata.run_by) from the identity used for authorization (identity_metadata.run_as). For interactive requests, these identify your user identity and the role respectively. Job workloads record the Jobs service's application service principal as run_by. See Verify audit attribution.

Job runs use the configured Run as identity. Query tasks can also depend on the SQL asset's sharing settings, and dedicated compute can use its assigned principal. See Set Run as to a group.

For features that are not supported or only partially supported when acting as a role, see Role-based access control (RBAC) limitations.

Additional resources

Resource	Description
Role-based access control (RBAC) limitations	Understand which Azure Databricks features are not supported or only partially supported when acting as a role.
Control workspace asset sharing with RBAC	Prevent users acting as a role from sharing workspace assets the role owns.
Manage permissions on a group	Grant or revoke the Assume permission on a group so users can assume the corresponding role.