Manage service principals

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

For an overview of service principals, see Service principals.

Add service principals to your account

Account admins and workspace admins can add service principals 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 Service principals tab, click Add service principal.
4. Enter a name for the service principal.
5. Click Add.

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 on the Identity and access tab.
4. Next to Service principals, click Manage.
5. Click Add service principal.
6. Click Add new.
7. Enter a name for the service principal.
8. Click Add.

Assign account-level admin roles to a service principal

1. As an account admin, log in to the account console.
2. In the sidebar, click User management.
3. On the Service principals tab, find and click the username.
4. On the Roles tab, select one or more roles.

Assign a service principal to a workspace

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

Account console

To add users to a workspace using the account console, the workspace must be enabled for identity federation.

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 service principal, assign the permission level (workspace User or Admin), and 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 on the Identity and access tab.
4. Next to Service principals, click Manage.
5. Click Add service principal.
6. Select an existing service principal.
7. Click Add.

Remove a service principal from a workspace

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

When a service principal is removed from a workspace, the service principal can no longer access the workspace, however permissions are maintained on the service principal. If the service principal is later added back to the workspace, it regains its previous permissions.

Account console

To remove service principals from a workspace using the account console, the workspace must be enabled for identity federation.

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 service principal.
5. Click the kebab menu at the far right of the service principal row and select Remove.
6. On the confirmation dialog, click Remove.

Workspace admin settings

When a service principal is removed from a workspace, the service principal can no longer access the workspace, however permissions are maintained on the service principal. If the service principal is later added back to a workspace, it regains its previous permissions.

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 Service principals, click Manage.
5. Select the service principal.
6. In the upper-right corner, click Delete.
7. Click Delete to confirm.

Assign the workspace admin role to a service principal

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 admins system group.
6. Click Add members.
7. Select the service principal and click Confirm.

To remove the workspace admin role from a service principal, remove the service principal from the admin group.

Deactivate a service principal

You can deactivate a service principal at either the account or workspace level. Deactivation prevents the service principal from authenticating and accessing Databricks APIs, but does not remove its permissions or objects. This is preferable to removal, which is a destructive action.

Effects of deactivation:

• The service principal cannot authenticate or access Databricks APIs.
• Applications or scripts that use the tokens generated by the service principal are no longer able to access the Databricks API. The tokens remain but cannot be used to authenticate while a service principal is deactivated.
• Compute resources owned by the service principal remain running.
• Scheduled jobs created by the service principal fail unless they are assigned to a new owner.

When reactivated, the service principal regains access with the same permissions.

Account level deactivation

Account admins can deactivate service principals across a Databricks account. When a service principal is deactivated at the account-level it cannot authenticate to the Databricks account or to any workspaces in the account.

You cannot deactivate a service principal using the account console. Instead, use the Account Service Principals API.

For example:

Bash

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

update-sp.json:

JSON

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": [
        {
          "value": "false"
        }
      ]
    }
  ]
}

Workspace level deactivation

When a service principal is deactivated at the workspace-level, it cannot authenticate to that specific workspace, but it can still authenticate to the account and other workspaces in the account.

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 Service principals, click Manage.
5. Select the service principal you want to deactivate.
6. Under Status, uncheck Active.

To set a service principal to active, perform the same steps, but check the checkbox instead.

Remove service principals from your Databricks account

Account admins can delete service principals from a Databricks account. Workspace admins cannot. When you delete a service principal from the account, that principal is also removed from their workspaces.

important

When you remove a service principal from the account, that service principal is also removed from their workspaces, regardless of whether or not identity federation has been enabled. We recommend that you refrain from deleting account-level service principals unless you want them to lose access to all workspaces in the account. Be aware of the following consequences of deleting service principals:

• Applications or scripts that use the tokens generated by the service principal can no longer access Databricks APIs
• Jobs owned by the service principal fail
• Compute owned by the service principal stop
• Queries or dashboards created by the service principal and shared using the Run as Owner credential have to be assigned to a new owner to prevent sharing from failing

To remove a service principal 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 Service principals tab, find and click the username.
4. On the Principal Information tab, click the kebab menu in the upper-right corner and select Delete.
5. In the confirmation dialog box, click Confirm delete.

Manage service principals using the API

Account admins and workspace admins can manage service principals in the Databricks account and workspaces using Databricks APIs. To manage roles on a service principal using the API, see Manage service principal roles using the Databricks CLI.

Manage service principals in the account using the API

Admins can add and manage service principals in the Databricks account using the Account Service Principals API. Account admins and workspace admins invoke the API using a different endpoint URL:

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

For details, see the Account Service Principals API.

Manage service principals in the workspace using the API

Account and workspace admins can use the Workspace Assignment API to assign service principals 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/{principal_id}.

See Workspace Assignment API.

If your workspace is not enabled for identity federation, a workspace admin can use the workspace-level APIs to assign service principals to their workspaces. See Workspace Service Principals API.

Manage tokens for a service principal

Service principals can authenticate to Databricks APIs using either OAuth tokens or personal access tokens, each with different scopes and security considerations:

• Databricks OAuth tokens

  • Authenticate to both account-level and workspace-level APIs.
  • OAuth tokens created at the account level can access both account and workspace APIs. OAuth tokens created at the workspace level are scoped to workspace APIs.
  • OAuth is recommended for most scenarios due to enhanced security and automatic token management.
  • For setup instructions, see the Authorize unattended access to Databricks resources with a service principal using OAuth.

• Personal access tokens

  • Authenticate only to workspace-level APIs.
  • Databricks recommends using PATs only when OAuth is not supported.
  • For more information, see the Databricks personal access token authentication.

Databricks recommends using OAuth tokens for service principal authentication whenever possible for improved security and lifecycle management. Use PATs only when OAuth is not available for your use case.