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.

Migrate workspace-local groups to account groups

Databricks recommends that you convert workspace-local groups to account groups to take advantage of a central place to administer identity. In order to convert workspace-local groups to account groups, you must make a new account group and then delete the existing workspace-local group, following these steps:

Step 1: Change the name of your workspace-local group

Two groups in a workspace cannot have the same name. You must change the name of your workspace-local group 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 2: Create a new account group

1. On the Groups tab, click Add Group.
2. Click Add new
3. Enter the name of the workspace-local group that you want to convert.
4. Click Add.
5. On the Members tab, click Add users, groups, or service principals.
6. On the dialog, browse or search for the users, service principals, and groups that are members of your workspace-local group and select them.
7. Click Confirm.

Step 3: Grant the account group access

You must grant the new account group access to the workspace-level objects and the functionality that the workspace-local group originally had access to so that the group members maintain that access. Follow the instructions in Manage entitlements to assign workspace entitlements to the new account groups, and use the Permissions API to grant the group access to objects within the workspace. For more information on access control, see Access control lists.

Step 4: Delete the workspace-local group

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

1. On the Groups tab, select the workspace-local group that you want to convert 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.

Sync workspace-local groups from your Microsoft Entra ID (formerly Azure Active Directory) tenant

You can sync groups from your Microsoft Entra ID (formerly Azure Active Directory) tenant to your Azure 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.