Manage workspace-local groups (legacy)

This article explains how admins create and manage legacy workspace-local groups. For an overview of account groups, the primary groups in Azure Databricks see Groups.

What are workspace-local groups?

Workspace-local groups are legacy groups. These groups are identified as having a source of Workspace. You can only use workspace-local groups in the workspace they are defined in. 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 or managed using account-level interfaces. To take advantage of centralized identity, Databricks recommends that you use account groups instead of workspace-local groups.

In identity federated workspaces, workspace-local groups can only be managed using the Workspace Groups API. In non-identity federated workspaces, workspace admins can also manage workspace-local groups using the workspace admin settings page.

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 automatic identity management to sync groups from Microsoft Entra ID to Azure 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 configure automatic identity management, see Sync users and groups automatically from Microsoft Entra ID.

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 Azure Databricks workspace.
2. Click your username in the top bar of the Azure 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.
2. Assign workspace entitlements on the new account groups, following the instructions in Manage entitlements on groups.
3. Use the UCX utilities group migration workflow to migrate the workspace-level groups’ permissions to workspace-level objects to the new account groups. See Step 2. Run the group migration workflow. You can also migrate permissions manually using the Permissions API.

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 Azure Databricks workspace.

2. Click your username in the top bar of the Azure 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

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

2. Click your username in the top bar of the Azure 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 Azure Databricks workspace.
2. Click your username in the top bar of the Azure 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.

View parent workspace-local groups

1. As a workspace admin, log in to the Azure Databricks workspace.
2. Click your username in the top bar of the Azure 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 Azure Databricks workspace.
2. Click your username in the top bar of the Azure 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.