Manage workspace-local groups (legacy)

This article explains how admins create and manage workspace-local groups. For an overview of account groups, see Manage groups.

What are workspace-local groups?

Workspace-local groups are legacy groups. These groups are identified as workspace-local in the workspace admin settings page. Workspace-local groups are not synchronized to the account as account groups. You can use workspace-local groups in the workspace they are defined in, but you cannot manage them using account-level interfaces. They cannot be assigned to additional workspaces or granted access to data in a Unity Catalog metastore. Workspace-local groups cannot be granted account-level roles. To take advantage of centralized identity, Databricks recommends that you use account groups instead of workspace-local groups.

Workspace admins can add and manage workspace-local groups using the workspace admin settings page, a provisioning connector for your identity provider, and the Workspace Groups API.

To manage access for workspace-local groups, see Authentication and access control.

Note

In identity federated workspaces, workspace-local groups can only be managed using the Workspace Groups API. Databricks began to enable new workspaces for identity federation and Unity Catalog automatically on March 6, 2024, with a rollout proceeding gradually across accounts. If your workspace is enabled for identity federation by default, it cannot be disabled. For more information, see Automatic enablement of Unity Catalog.

Migrate workspace-local groups to account groups

Databricks recommends converting workspace-local groups to account groups for centralized identity administration.

Step 1: Migrate workspace-level SCIM provisioning to the account

Databricks recommends that you configure account-level SCIM provisioning to sync groups from your identity provider to Databricks. If you currently have workspace-level SCIM provisioning set up for your workspaces, you must disable the workspace-level SCIM provisioner. Otherwise, workspace-level SCIM continues to create and update workspace-local groups. To set up a new SCIM provisioning connector for your account and disable workspace-level SCIM, see Migrate workspace-level SCIM provisioning to the account level.

Step 2: Change the name of your workspace-local groups

Two groups in a workspace cannot have the same name. You must change the name of your workspace-local groups in order to add a new account group to the workspace with the same name. These steps recommend adding (workspace) to the group’s name.

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click the Groups tab and select the workspace-local group that you want to convert to an account group.

  4. Under Name, add (workspace) to the end of the group’s name.

  5. Click Save.

Step 3: Grant the account groups permissions

Grant the newly provisioned account groups access to the same functionalities their workspace-local counterparts had. For each new account group:

  1. Grant the group access to your workspace. See Assign a group to a workspace using the account console.

  2. Assign workspace entitlements on the new account groups, following the instructions in Manage entitlements on groups.

  3. Use the Permissions API to assign the workspace-level groups’ permissions to workspace-level objects to the new account groups.

Step 4: Delete the workspace-local groups

Now that you have migrated your workspace-local group to the account and you can delete your workspace-local groups.

  1. On the Groups tab, select the workspace-local group that you converted to an account group.

  2. Click x Delete and click Delete to confirm.

Manage workspace-local groups using the API

Workspace admins can add and manage workspace-local groups using the workspace-level SCIM API. In identity federated workspaces, workspace-local groups can only be managed using the API. For instructions, see Workspace Groups API.

Manage workspace-local groups using the admin settings page

Workspace admins can add and manage workspace-local groups using the workspace admin settings page in non-identity federated workspaces.

Create a workspace-local group using the admin settings page

To add a workspace-local group to a workspace using the admin settings, do the following:

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click on the Identity and access tab.

  4. Next to Groups, click Manage.

  5. Click Create Group.

  6. Enter a group name and click Create.

    Group names must be unique. You cannot change a group name. If you want to change a group name, you must delete the group and recreate it with the new name.

Add members to a workspace-local group using the admin settings page

Note

You cannot add a child group to the admins group.

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click on the Identity and access tab.

  4. Next to Groups, click Manage.

  5. Select the group you want to update.

  6. On the Members tab, click Add users, groups, or service principals.

  7. On the dialog, browse or search for the users, service principals, and groups you want to add and select them.

  8. Click Confirm.

    You might need to click the down arrow in the selector to hide the drop-down list and show the Confirm button.

Remove a user, group, or service principal from a workspace-local group

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click on the Identity and access tab.

  4. Next to Groups, click Manage.

  5. Select the group you want to update.

  6. On the Members tab, find the user, group, or service principal you want to remove and click the X in the Actions column.

  7. Click Remove Member to confirm.

Note

You can also remove a child workspace-local group from its parent workspace-local group by going to the Parents tab for the group you want to remove. Find the parent group you want to remove the child workspace-local group from and click the X in the Actions column.

View parent workspace-local groups

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click on the Identity and access tab.

  4. Next to Groups, click Manage.

  5. Select the group you want to view.

  6. On the Parent groups tab, view the parent groups for your group.

Change the name of a group

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click on the Identity and access tab.

  4. Next to Groups, click Manage.

  5. Select the group you want to view.

  6. Under Name, update the name.

  7. Click Save.

Sync workspace-local groups from an identity provider

You can sync groups from your identity provider (IdP) to your Databricks workspace using a workspace-level SCIM provisioning connector. Workspace-level SCIM provisioning creates workspace-local groups that can only be used in your workspace. Databricks recommends using account-level SCIM provisioning instead.

For instructions, see Provision identities to a Databricks workspace (legacy).