Skip to main content
Last updated on

Switch roles

Preview

This feature is in Public Preview.

You can assume a role in Databricks in several ways. In all cases, your user-identity permissions are replaced by the role's permissions for the duration of the session or connection, and all actions are attributed to the role.

To assume a role, you must have Assume permission on it, either directly or as a member of the backing group. See Manage permissions on a group.

important

All groups assigned to a workspace inherit permissions from the workspace's users system group, which includes all workspace users. While acting as a role, you still see catalogs, Unity Catalog objects, workspace assets, and compute shared with all workspace users, in addition to what has been granted directly to the role. To limit what the role can see, reduce the permissions of the users system group in your workspace.

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 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.

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 Assume permission on a group assigned to the workspace. See Manage permissions on a group.

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. 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, because roles are workspace-specific.

To find a group's ID, see Manage groups. 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, your permissions automatically down-scope to that group's permissions for all operations on that compute. This is equivalent to assuming the group as a role for the duration of the compute session, and applies to notebooks, queries, and any other workloads that run on the compute. Unlike the other methods, you do not switch roles in the workspace UI first: connecting to the compute is what scopes you to the group.

For details on setting up dedicated compute for a group, see Dedicated compute group access.

CLI​

When you authenticate to a Databricks workspace using the CLI, the CLI opens your web browser to complete the authentication flow. If you have 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.

Bash
databricks auth login --host <workspace-url>

After you complete the login flow, the CLI authorizes all operations using this profile as the role you selected. For example:

Bash
databricks warehouses list --profile <profile-name>

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

API (OAuth token exchange)​

You can generate an OAuth token scoped to a role, which you can use to make API calls as that role. The scoped token authorizes all API operations as the role.

To generate a role-scoped token, run databricks auth login as described in CLI and select the role in your web browser. The resulting token is scoped to that role.

You can also manually generate a role-scoped OAuth token by passing the underlying group ID as the assume_group parameter during the OAuth authorization code flow. For details, see Authorize user access to Databricks with OAuth.

Third-party BI tools​

Third-party BI tools that support OAuth (such as Tableau and Power BI) can authorize as a role. Once configured, the BI tool authorizes all queries it executes as the role. This authorization works with all compute and SQL warehouse types.

What changes when you assume a role​

Regardless of which method you use to assume a role:

  • Notebooks and queries run as the role. The role's permissions are used for all data access and Unity Catalog operations.
  • Jobs created while acting as the role have their Run as set to the role automatically. You can also set a job's Run as to a group without assuming it first. See Set Run as to a group.
  • The role owns any workspace assets you create (notebooks, SQL queries, SQL warehouses, jobs).
  • Audit logs record identity_metadata.run_by as your user identity and identity_metadata.run_as as the role.

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

Next steps​

On this page