Manage groups

This page explains how to manage groups for your Databricks account and workspaces.

For an overview of groups, see Groups.

Sync groups to your Databricks account from an identity provider

You can sync groups from your identity provider (IdP) to your Databricks account using a SCIM provisioning connector. For instructions, see Sync users and groups to your Databricks account.

Add groups to your account

Account admins and workspace admins can add groups to the Databricks account using the account console or the workspace admin settings page.

Account console

1. As an account admin, log in to the account console.
2. In the sidebar, click User management.
3. On the Groups tab, click Add group.
4. Enter a name for the group.
5. Click Confirm.
6. When prompted, add users, service principals, and groups to the group.

Workspace admin settings

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 Identity and access tab.
4. Next to Groups, click Manage.
5. Click Add Group.
6. Click Add new.
7. Enter a name for the group.
8. Click Add.

Add members to a group

Account admins and workspace admins can add groups to the Databricks account using the account console or the workspace admin settings page. Group managers that are not workspace admins must manage group membership using the Account Groups API.

note

To keep external groups in sync with your identity provider, you cannot manage membership of external groups in the account console by default. To update external group membership from the Databricks UI, an account admin can disable Immutable external groups preview in the account console preview page. External groups that are managed using automatic identity management cannot not be updated in Databricks even when the immutable external groups preview is disabled.

Account console

1. As an account admin, log in to the account console.
2. In the sidebar, click User management.
3. On the Groups tab, select the group you want to update.
4. Click Add members.
5. Search for the user, group, or service principal you want to add and select it.
6. Click Add.

There is a delay of a few minutes between updating a group from an account and the group being updated in workspaces.

Workspace admin settings

note

You cannot add a child group to the admins group. You cannot add workspace-local groups or system groups as members of account 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 the Identity and access tab.
4. Next to Groups, click Manage.
5. Select the group you want to update. You must have the group manager role on the group to update it.
6. On the Members tab, click Add members.
7. In the dialog, browse or search for the users, service principals, and groups you want to add and select them.
8. Click Confirm.

Change the name of a group

Account admins can update the name of groups in using the account console and group managers can update the name of groups using the Account Groups API. To keep external groups in sync with your identity provider, you cannot update the name of an external groups in the account console by default.

Account console

1. As an account admin, log in to the account console.
2. In the sidebar, click User management.
3. On the Groups tab, select the group you want to update.
4. Click Group information.
5. Under Name, update the name.
6. Click Save.

Account Groups API

Bash

curl --netrc -X PATCH \
https://${DATABRICKS_HOST}/api/2.1/accounts/{account_id}/scim/v2/Groups/{id} \
--header 'Content-type: application/scim+json' \
--data @update-group.json \
| jq .

update-group.json:

JSON

{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ],
  "Operations": [
    {
      {
          "op": "replace",
          "path": "displayName",
          "value": "<updated-name>"
      }
    }
  ]
}

For information on how to authenticate to Account Groups API, see Authorizing access to Databricks resources.

Assign a group to a workspace

Account admins and workspace admins can assign groups to a Databricks workspace using the account console or the workspace admin settings page.

Account console

To add groups to a workspace using the account console, the workspace must be enabled for identity federation. Workspace-local groups are not assignable to workspaces.

1. As an account admin, log in to the account console.
2. In the sidebar, click Workspaces.
3. Click your workspace name.
4. On the Permissions tab, click Add permissions.
5. Search for and select the group, assign the permission level (workspace User or Admin), and then click Save.

Workspace admin settings

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 Identity and access tab.
4. Next to Groups, click Manage.
5. Click Add Group.
6. Select an existing group to assign to the workspace.
7. Click Add.

Remove a group from a workspace

When an account group is removed from a workspace, group members can no longer access the workspace, however permissions are maintained on the group. If the group is later added back to a workspace, the group regains its previous permissions.

Account admins and workspace admins can remove a group from a Databricks workspace using the account console or the workspace admin settings page.

Account console

To remove groups to a workspace using the account console, the workspace must be enabled for identity federation. Workspace-local groups cannot be removed from workspaces using the account console.

1. As an account admin, log in to the account console.
2. In the sidebar, click Workspaces.
3. Click your workspace name.
4. On the Permissions tab, find the group.
5. Click the kebab menu at the far right of the group row and select Remove.
6. In the confirmation dialog, click Remove.

Workspace admin settings

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 Identity and access tab.
4. Next to Groups, click Manage.
5. Select the group and click x Delete
6. Click Delete to confirm.

Manage roles on a group

Preview

This feature is in Public Preview.

Account admins can grant roles on groups in the account console and workspace admin can manage group roles using the workspace admin settings page. Group managers that are not workspace admins can manage group roles using the Account Access Control API.

Account console

1. As an account admin, log in to the account console.
2. In the sidebar, click User management.
3. On the Groups tab, find and click the group name.
4. Click the Permissions tab.
5. Click Grant access.
6. Search for and select the user, service principal, or group and choose the Group: Manager role.
7. Click Save.

Workspace admin settings

You cannot assign workspace-local groups or system groups roles on account 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 the Identity and access tab.
4. Next to Groups, click Manage.
5. Select the group you want to update. You must have the group manager role on the group to update it.
6. Click the Permissions tab.
7. Click Grant access.
8. Search for and select the user, service principal, or group and choose the Group: Manager role.
9. Click Save.

Assign account admin roles to a group

You cannot assign the account admin roles to a group using the account console, but you can assign it to groups using the Account Groups API. For example:

Bash

curl --netrc -X PATCH \
https://${DATABRICKS_HOST}/api/2.1/accounts/{account_id}/scim/v2/Groups/{id} \
--header 'Content-type: application/scim+json' \
--data @update-group.json \
| jq .

update-group.json:

JSON

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "roles",
      "value": [
        {
          "value": "account_admin"
        }
      ]
    }
  ]
}

For information on how to authenticate to Account Groups API, see Authorizing access to Databricks resources.

View parent 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 group tab, view the parent groups for your group.

Remove groups from your Databricks account

Account admins can remove groups from a Databricks account. Group managers can also remove groups from the account using the Account Groups API, see Manage groups using the API. If you remove a group using the account console, you must ensure that you also remove the group using any SCIM provisioning connectors or SCIM API applications that have been set up for the account. If you don't, SCIM provisioning will simply add the group and its members back the next time it syncs. See Sync users and groups from your identity provider using SCIM.

important

When you remove a group, all users in that group are deleted from the account and lose access to any workspaces they had access to (unless they are members of another group or have been directly granted access to the account or any workspaces). Databricks recommends that you refrain from deleting account-level groups unless you want them to lose access to all workspaces in the account. Be aware of the following consequences of deleting users:

• Applications or scripts that use the tokens generated by the user can no longer access Databricks APIs.
• Jobs owned by the user fail.
• Clusters owned by the user stop.
• Libraries installed by that user are invalid and must be reinstalled.
• Queries or dashboards created by the user and shared using the Run as Owner credential have to be assigned to a new owner to prevent sharing from failing.

To remove a group using the account console, do the following:

1. As an account admin, log in to the account console.
2. In the sidebar, click User management.
3. On the Groups tab, find the group you want to remove.
4. Click the kebab menu at the far right of the user row and select Delete.
5. In the confirmation dialog box, click Confirm delete.

Manage groups using the API

Account admins and workspace admins and group managers can add, delete, and manage groups in the Databricks account using the Account Groups API. Account admins and workspace admins and group managers must invoke the API using a different endpoint URL:

• Account admins use {account-domain}/api/2.1/accounts/{account_id}/scim/v2/.
• Workspace admins and group managers use {workspace-domain}/api/2.0/account/scim/v2/.

For details, see the Account Groups API.

Account and workspace admins can use the Workspace Assignment API to assign groups to workspaces enabled for identity federation. The Workspace Assignment API is supported through the Databricks account and workspaces.

• Account admins use {account-domain}/api/2.0/accounts/{account_id}/workspaces/{workspace_id}/permissionassignments.
• Workspace admins use {workspace-domain}/api/2.0/preview/permissionassignments/principals/{group_id}.

See Workspace Assignment API.

Manage roles for a group using the API

Preview

This feature is in Public Preview.

Groups managers can manage group roles using the Accounts Access Control API. Account admins and workspace admins and group managers must invoke the API using a different endpoint URL:

• Account admins use {account-domain}/api/2.0/preview/accounts/{account_id}/access-control/assignable-roles.
• Workspace admins and group managers use {workspace-domain}/api/2.0/preview/accounts/access-control/assignable-roles.

See Account Access Control API and Accounts Access Control Workspace Proxy API.

API examples for managing groups

The following examples show how workspace admins can use the Account Groups API and the Workspace Assignment API to manage groups. Workspace admins authenticate to their workspace using an API token.

Create an account group

Bash

curl --request POST \
  --location '{workspace-domain}/api/2.0/account/scim/v2/Groups' \
  --header 'Authorization: Bearer $OAUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "<group-name>"
  }'

This returns a group ID for the new account group. Save it for reference in the following API examples.

Add a group to your workspace

The following example adds a group to your workspace with workspace user permissions. You can also set permissions to [“ADMIN”] to grant the group the workspace admin role.

Bash

curl --location --request PUT '{workspace-domain}/api/2.0/preview/permissionassignments/principals/{group-id}' \
  --header 'Authorization: Bearer $OAUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "permissions": ["USER"]
  }'

Remove a group from your workspace

The following example removes a group from your workspace. Removing a group from your workspace does not delete the group from the account.

Bash

curl --location --request PUT '{workspace-domain}/api/2.0/preview/permissionassignments/principals/{group-id}' \
  --header 'Authorization: Bearer $OAUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "permissions": []
  }'

Add a member to a group

Bash

curl --location --request PATCH '{workspace-domain}/api/2.0/accounts/{account_id}/scim/v2/Groups/{group-id}' \
  --header 'Authorization: Bearer $OAUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
      {
        "op": "add",
        "value": {
          "members": [
            {
              "value": "{user-id}"
            }
          ]
        }
      }
    ]
  }'