Manage service principals

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

For an overview of service principals, see Service principals.

Sync service principals to your Azure Databricks account from your Microsoft Entra ID tenant

You can sync Microsoft Entra ID service principals automatically from your Microsoft Entra ID tenant to your Azure Databricks account using automatic identity management (Public Preview). Databricks uses Microsoft Entra ID as the source, so any changes to users or group memberships are respected in Azure Databricks. To enable automatic identity management, see Sync users and groups automatically from Microsoft Entra ID.

SCIM provisioning does not support syncing service principals.

Add service principals to your account

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

Service principals can either be created in Azure Databricks or linked from an existing Microsoft Entra ID service principal. See Databricks and Microsoft Entra ID service principals. When automatic identity management is enabled, you can search for and add service principals directly from Microsoft Entra ID.

Account admins and workspace admins can add service principals to the Azure 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. Under Management, choose Databricks managed or Microsoft Entra ID managed.
5. If you chose Microsoft Entra ID managed, under Microsoft Entra application ID, paste the application (client) ID for the service principal.
6. Enter a name for the service principal.
7. Click Add.

Workspace admin settings

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 Service principals, click Manage.

5. Click Add service principal.

6. Click Add new.

7. Select Databricks managed or Microsoft Entra ID managed. If you select Microsoft Entra ID managed, paste the application (client) ID for the service principal.

8. Enter a name for the service principal.

9. 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 Azure 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 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 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 Azure 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 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 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 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 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 an Azure Databricks account. When a service principal is deactivated at the account-level it cannot authenticate to the Azure 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:

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:

{
  "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 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 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 Azure Databricks account

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

When a Microsoft Entra ID service principal is removed from an account, the service principal can no longer access the account or its workspaces, however permissions are maintained on the service principal. If the service principal is later added back to the account, it regains its previous permissions.

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 Azure 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 Azure 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 Azure 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:

• Azure 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 Azure 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 Azure 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.

For details on working with Microsoft Managed Service Identities (MSI) or Microsoft Entra ID access tokens, see Azure managed identities authentication and MS Entra service principal authentication respectively.