Manage service principals

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

For an overview of the Databricks identity model, see Databricks identities and roles.

What is a service principal?

A service principal is an identity that you create in Databricks for use with automated tools, jobs, and applications. Service principals give automated tools and scripts API-only access to Databricks resources, providing greater security than using users or groups. It also prevents jobs and automations from failing if a user leaves your organization or a group is modified.

You can grant and restrict a service principal’s access to resources in the same way as you can a Databricks user. For example, you can do the following:

• Give a service principal account admin and workspace admin roles.

• Give a service principal access to data, either at the account level using Unity Catalog, or at the workspace level.

• Add workspace entitlements to a service principal.

• Add a service principal to a group at both the account and workspace level, including the workspace admins group.

Unlike a Databricks user, a service principal is an API-only identity; it cannot be used to access the Databricks UI.

Note

Service Principals are managed within Databricks. They do not integrate with Google Cloud Service Accounts.

Databricks recommends that you enable your workspaces for identity federation so that you can manage your service principals in the account. If your workspace isn’t enabled for identity federation, you can create and manage service principals using the workspace-level SCIM APIs.

Add a service principal to your Databricks account

Account admins can add service principals to your Databricks account using the account console or the SCIM (Account) API.

Add service principals to your account using the account console

To add a service principal to the account using the account console:

1. As an account admin, log in to the account console.

2. Click User management.

3. On the Service principals tab, click Add service principal.

4. Enter a name for the service principal.

5. Click Add.

To use service principals, you must add them to a workspace and generate access tokens for them in the workspace. See Add a service principal to a workspace.

Add service principals to your account using the SCIM (Account) API

Account admins can add and manage service principals in the Databricks account using the SCIM API for Accounts.

Workspace admins can also create and manage service principals using this API, but they must invoke the API using a different endpoint URL:

• Account admins use accounts.gcp.databricks.com/api/2.0/accounts/{account_id}/scim/v2/.

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

For details, see SCIM API 2.0 (Accounts).

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 federated as 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 will no longer be able to access the Databricks API

• Jobs owned by the service principal will fail

• Clusters owned by the service principal will stop

• Queries or dashboards created by the service principal and shared using the Run as Owner credential will 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. 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.

Add a service principal to a workspace

Account admins can add service principals to identity federated workspaces using the account console and the Workspace Assignment API.

Workspace admins can manage service principals in their identity federated workspaces using the workspace admin console and the Workspace Assignment API.

Workspace admins can manage service principals in their non-identity federated workspaces using the workspace-level SCIM (ServicePrincipals) API.

Assign a service principal to a workspace using the account console

To add service principals 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. Click Workspaces.

3. On the Permissions tab, click Add permissions.

4. Search for and select the service principal, assign the permission level (workspace User or Admin), and click Save.

Add a service principal to a workspace using the admin console

To add a service principal to a workspace using the workspace admin console, the workspace must be enabled for identity federation.

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 Console.

3. On the Service principals tab, click Add service principal.

4. Select an existing service principal to assign to the workspace or create a new one.

   To create a new service principal, click the drop-down arrow in the search box and then click + Add new service principal.

Note

If your workspace is not enabled for identity federation, you cannot assign existing account service principals to your workspace or use the admin console to add a new service principal to your workspace.

Assign a service principal to a workspace using REST APIs

The REST APIs that you can use to assign service principals to workspaces depend on whether the workspace is enabled for identity federation:

• Workspace enabled for identity federation: Account and workspace admins can use the Workspace Assignment API to assign service principals to workspaces. See the Workspace Assignment (Account) API and Workspace Assignment (Workspace) API reference

• Workspace not enabled for identity federation: A workspace admin can use the workspace-level SCIM (ServicePrincipal) API to assign service principals to their workspaces. See SCIM API 2.0 (ServicePrincipals) for workspaces.

Remove a service principal from a workspace

Account admins can remove service principals to identity federated workspaces using the account console and the Workspace Assignment API.

Workspace admins can remove service principals in their identity federated workspaces using the workspace admin console and the Workspace Assignment API.

Workspace admins can remove service principals in their non-identity federated workspaces using the workspace-level SCIM (ServicePrincipals) API.

Remove a service principal from a workspace using the account console

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

1. Click Workspaces.

2. On the Permissions tab, find the service principal.

3. Click the kebab menu at the far right of the service principal row and select Remove.

4. In the confirmation dialog box, click Remove.

Remove a service principal from a workspace using the admin console

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

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 Console.

3. On the Service principals tab, find the service principal and click the at the far right of the user row.

4. Click Delete to confirm.

Remove a service principal from a workspace using REST APIs

The REST APIs that you can use to remove service principals from workspaces depend on whether the workspace is enabled for identity federation as follows:

• Workspace enabled for identity federation: Account and workspace admins can use the Workspace Assignment API to remove service principals to workspaces. See the Workspace Assignment (Account) API and Workspace Assignment (Workspace) API reference

• Workspace not enabled for identity federation: A workspace admin can use the workspace-level SCIM (ServicePrincipal) API to remove service principals from their workspaces. See SCIM API 2.0 (ServicePrincipals) for workspaces.

Manage access tokens for a service principal

To authenticate a service principal to APIs on Databricks, an administrator can create a Databricks Personal Access Tokens on behalf of the service principal.

1. Grant the Can Use token permission to the service principal.

2. Create a Databricks personal access token on behalf of the service principal using the POST /token-management/on-behalf-of/tokens operation in the token management REST API. An administrator can also list personal access tokens and delete them using the same API.

Note

It’s not possible to create, list, or manage a token for a service principal from within the Databricks UI.

Manage entitlements for a service principal

An entitlement is a property that allows a user, service principal, or group to interact with Databricks in a specified way. Entitlements are assigned to users at the workspace level. The following table lists entitlements and the workspace UI and API property name that you use to manage each one. You can use the workspace admin console and workspace-level SCIM REST APIs to manage entitlements.

Entitlement name (UI)	Entitlement name (API)	Default	Description
Workspace access	workspace-access	Granted by default.	When granted to a user or service principal, they can access the Data Science & Engineering and Databricks Machine Learning persona-based environments. Can’t be removed from workspace admins.
Databricks SQL access	databricks-sql-access	Granted by default.	When granted to a user or service principal, they can access Databricks SQL.
Allow unrestricted cluster creation	allow-cluster-create	Not granted to users or service principals by default.	When granted to a user or service principal, they can create clusters. You can restrict access to existing clusters using cluster-level permissions. Can’t be removed from workspace admins.
Allow pool creation (not available via UI)	allow-instance-pool-create	Can’t be granted to individual users or service principals.	When granted to a group, its members can create instance pools. Can’t be removed from workspace admins.

To add or remove an entitlement for a service principal, use the SCIM API 2.0 (ServicePrincipals) for workspaces API.