Manage service principals

Preview

This feature is in Public Preview.

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.

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.

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 Account Console user management icon 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/.

To add a service principal using the SCIM API:

  1. Use the SCIM API 2.0 (Accounts) to determine whether the service principal already exists.

  2. If the service principal does not exist, create the principal using the same API.

For details, see SCIM API 2.0 (Accounts).

Assign account admin rights to a service principal

To assign account admin rights using the account console, do the following:

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

  2. Click Account Console user management icon User management.

  3. On the Service principals tab, find and click the username.

  4. On the Roles tab, turn on Account admin.

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. You should 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 Account Console user management icon User management.

  3. On the Service principals tab, find and click the username.

  4. On the Principal Information tab, click the Kebab menu kebab menu to the far upper right and select Delete.

  5. In the confirmation dialog box, click Confirm delete.

Add a service principal to a workspace

A workspace admin can use the workspace-level SCIM (ServicePrincipal) API to add service principals to their workspaces. See SCIM API 2.0 (ServicePrincipals) for workspaces.

Remove a service principal from a workspace

A workspace admin can use the workspace-level SCIM (ServicePrincipal) API to remove service principals from 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.