Manage workspace-local groups

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.

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.

Note

In identity federated workspaces, workspace-local groups can only be managed using the Workspace Groups API.

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.

You can use any of the following methods to migrate workspace-local groups to the account level:

  • Convert them manually. Create a new account group using the account console and add each member to the new account. Then use the workspace admin settings page to delete the workspace-local group.

    See Add groups to your account using the account console.

  • Convert them using a SCIM provisioning connector. Set up or modify a SCIM provisioning connector to add a group to the account that replicates the workspace-local group. Then delete the group using the workspace admin settings page or Workspace Groups API. If you have an active SCIM provisioning connector for the workspace, you should shut it down. You should be provisioning all users and groups at the account level.

    See Sync users and groups from your identity provider.

  • Convert them using the SCIM APIs. Use the Account Groups API to add a group to the account that replicates the workspace-local group. Then delete the group using the workspace admin settings page or Workspace Groups API.

    See the Account Groups API and Workspace Groups API.

After you migrate the workspace-local group to the account, you need to grant the new account group access to the workspace and the objects, and the functionality that the workspace-local group originally had access to so that the group members maintains that access. Follow the instructions in Assign a group to a workspace using the account console to assign workspace permissions to the new account groups, and use the Permissions API to grant the group access to objects within the workspace.

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

  3. On the Groups tab, click Create Group.

  4. 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 Admin Settings.

  3. On the Groups tab, select the group you want to update.

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

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

  6. 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 Admin Settings.

  3. Select the group you want to update.

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

  5. Click Remove Member to confirm.

The user, group, or service principal loses all child group memberships and entitlements and instance profiles granted by virtue of membership in this group. However, the identity might retain those entitlements by virtue of membership in other groups or user-level grants.

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.

All entitlements and instance profiles assigned to the parent group are removed from the members of the group. However, they might retain those entitlements and instance profiles by virtue of membership in other groups or user-level grants.

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

  3. Click the Groups tab and select the group you want to view.

  4. On the Parents 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 Admin Settings.

  3. Click the Groups tab and select the group you want to view.

  4. Under Name, update the name.

  5. Click Save.

Manage a workspace-local group’s workspace entitlements

Workspace admins can manage group entitlements for workspace-local groups using the admin settings page. For more information, see Add an entitlement for a group using the workspace admin settings page.

Sync workspace-local groups to your Databricks account from an identity provider

You can sync groups from your identity provider (IdP) to your Databricks workspace using a SCIM provisioning connector. For instructions, see Provision identities to a Databricks workspace.