Manage service principals

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

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

What is a service principal?

A service principal is an identity that you create in Azure Databricks for use with automated tools, jobs, and applications. Service principals give automated tools and scripts API-only access to Azure Databricks resources, providing greater security than using users or groups.

You can grant and restrict a service principal’s access to resources in the same way as you can an Azure 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 a service principal to a group at both the account and workspace level, including the workspace admins group.

You can also grant Azure Databricks users, service principals, and groups permissions to use a service principal. This allows users to run jobs as the service principal, instead of as their identity. This prevents jobs from failing if a user leaves your organization or a group is modified.

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

Azure 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 in your workspace.

Important

If your account was created after November 9, 2023, identity federation is enabled on all new workspaces by default, and it cannot be disabled.

Who can manage and use service principals?

To manage service principals in Azure Databricks, you must have one of the following: the account admin role, the workspace admin role, or the manager or user role on a service principal.

• Account admins can add service principals to the account and assign them admin roles. They can also assign service principals to workspaces, as long as those workspaces use identity federation.
• Workspace admins can add service principals to an Azure Databricks workspace, assign them the workspace admin role, and manage access to objects and functionality in the workspace, such as the ability to create clusters or access specified persona-based environments.
• Service Principal Managers can manage roles on a service principal. The creator of a service principal becomes the service principal manager. Account admins are service principal managers on all service principals in an account.

Note

If a service principal was created before June 13, 2023, then the creator of the service principal does not have the service principal manager role by default. Ask an account admin to grant you the service principal manager role.

• Service Principal Users can run jobs as the service principal by updating the job’s Run as setting to the service principal. The job runs using the identity of the service principal, instead of the identity of the job’s owner. The service principal user must have the Can Manage or Is Owner permission on the job to update the job’s Run as setting. For more information, see Run a job as a service principal.

For information on how to grant the service principal manager and user roles, see Roles for managing service principals.

Manage service principals in your account

Account admins can add service principals to your Azure Databricks account using the account console.

To use service principals on Azure Databricks, an admin user must create a new Microsoft Entra ID (formerly Azure Active Directory) application and then add it to the Azure Databricks workspace to use as a service principal. To create a Microsoft Entra ID service principal, follow these instructions:

1. Sign in to the Azure portal.

   Note

   The portal to use is different depending on whether your Microsoft Entra ID (formerly Azure Active Directory)> application runs in the Azure public cloud or in a national or sovereign cloud. For more information, see National clouds.

2. If you have access to multiple tenants, subscriptions, or directories, click the Directories + subscriptions (directory with filter) icon in the top menu to switch to the directory in which you want to provision the service principal.

3. Search for and select Microsoft Entra ID.

4. Click + Add and select App registration.

5. For Name, enter a name for the application.

6. In the Supported account types section, select Accounts in this organizational directory only (Single tenant).

7. Click Register.

8. Within Manage, click Certificates & secrets.

9. On the Client secrets tab, click New client secret.

   

10. In the Add a client secret pane, for Description, enter a description for the client secret.

11. For Expires, select an expiry time period for the client secret, and then click Add.

12. Copy and store the client secret’s Value in a secure place, as this client secret is the password for your application.

13. On the application page’s Overview page, in the Essentials section, copy the following values:

    • Application (client) ID
    • Directory (tenant) ID

    

Add service principals to your account using the 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. Under UUID, paste the Application (client) ID for the service principal.
6. Click Add.

Assign account admin roles to a service principal

1. As an account admin, log in to the account console.
   1. In the sidebar, click User management.
   2. On the Service principals tab, find and click the username.
   3. On the Roles tab, turn on Account admin or Marketplace admin.

To use service principals as account admins, you must generate Microsoft Entra ID tokens for them. See Get Microsoft Entra ID (formerly Azure AD) tokens for service principals.

Assign a service principal to a workspace using the account console

To add users to a workspace using the account console, the workspace must be enabled for identity federation. Workspace admins can also assign service principals to workspaces using the workspace admin settings page. For details, see Add a service principal to a workspace using the workspace admin settings.

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.

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

Deactivate a service principal in your Azure Databricks account

Account admins can deactivate service principals across an Azure Databricks account. A deactivated service principal cannot authenticate to the Azure Databricks account or workspaces. However, all of the service principal’s permissions and workspace objects remain unchanged. When a service principal is deactivated the following is true:

• The service principal cannot authenticate to the account or any of their workspaces from any method.
• 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.
• Clusters owned by the service principal remain running.
• Scheduled jobs created by the service principal fail unless they are assigned to a new owner.

When a service principal is reactivated, they can login to Azure Databricks with the same permissions. Azure Databricks recommends deactivating service principals from the account instead of removing them because removing a service principal is a destructive action. See Remove service principals from your Azure Databricks account. When you deactivate a service principal from the account, that service principal is also deactivated from their identity federated workspaces.

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

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.

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
• Clusters 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 in your workspace

Workspace admins can manage service principals in their workspaces using the workspace admin settings page.

Add a service principal to a workspace using the 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 Admin Settings.

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

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

   To add a new service principal, click the drop-down arrow in the search box and then click + Add new service principal. Paste the Application (client) ID for the service principal and enter a display name.

Note

If your workspace is not enabled for identity federation, you cannot assign existing account service principals to your workspace.

Assign the workspace admin role to a service principal using the workspace admin settings page

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 Admin Settings.
3. On the Groups tab, select the Admins group.
4. Click Add users or service principals.
5. 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.

Manage workspace entitlements for a service principal

An entitlement is a property that allows a user, service principal, or group to interact with Azure 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 settings page 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.

The users group is granted the Workspace access and Databricks SQL access entitlements by default. All workspace users and service principals are members of the users group. To assign these entitlements on a user-by-user basis, a workspace admin must remove the entitlement from the users group and assign it individually to users, service principals, and groups.

Important

To log in and access Azure Databricks, a user must have the Databricks SQL access or Workspace access entitlement.

You cannot grant the allow-instance-pool-create entitlement using the admin settings page. Instead, use the Workspace Users, Service Principals, or Groups API.

Add or remove an entitlement for a user using the workspace admin settings page

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 Admin Settings.
3. On the Service principals tab, select the service principal you want to update.
4. To add an entitlement, select the corresponding checkbox.
5. To remove an entitlement, deselect the corresponding checkbox.

Deactivate a service principal in your Azure Databricks workspace

Workspace admins can deactivate service principals in a Azure Databricks workspace. A deactivated service principal cannot access the workspace from Azure Databricks APIs, however all of the service principal’s permissions and workspace objects remain unchanged. When a service principal is deactivated:

• The service principal cannot authenticate to the workspaces from any method.
• Applications or scripts that use the tokens generated by the service principal can no longer access the Databricks API. The tokens remain but cannot be used to authenticate while a service principal is deactivated.
• Clusters owned by the service principal remain running.
• Scheduled jobs created by the service principal have to be assigned to a new owner to prevent them from failing.

When a service principal is reactivated, they can authenticate to the workspace with the same permissions. Azure Databricks recommends deactivating service principal instead of removing them because removing a service principal is a destructive action.

A deactivated service principal’s status is labeled Inactive in the workspace admin settings page.

You cannot deactivate a service principal using the workspace admin settings page. Instead, use the Workspace Service Principals API. See Deactivate a service principal in your Azure Databricks workspace using the API.

Remove a service principal from a workspace using the workspace admin settings page

Removing a service principal from a workspace does not remove the service principal from the account. To remove a service principal from your account, see Remove service principals from your Azure Databricks 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 Admin Settings.
3. On the Service principals tab, find and click the name.
4. In the upper-right corner, click Delete.
5. Click Delete to confirm.

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

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.0/accounts/{account_id}/scim/v2/.
• Workspace admins use {workspace-domain}/api/2.0/account/scim/v2/.

For details, see the Account Service Principals API.

Deactivate a service principal using the API

Account admins can change a service principal’s status to false to deactivate the service principal using the Account Service Principals API.

For example:

curl --netrc -X PATCH \
https://<account-domain>/api/2.0/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"
        }
      ]
    }
  ]
}

A deactivated service principal’s status is labeled Inactive in the account console. When you deactivate a service principal from the account, that service principal is also deactivated from its workspaces.

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.

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.

Deactivate a service principal in your Azure Databricks workspace using the API

Workspace admins can change a service principal’s status to false to deactivate the service principal using Workspace Service Principals API. For example:

curl --netrc -X PATCH \
https://<databricks-instance>/api/2.0/preview/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"
        }
      ]
    }
  ]
}

A deactivated service principal’s status is labeled Inactive in the workspace admin settings page.

Manage tokens for a service principal

To authenticate a service principal to APIs on Azure Databricks, an administrator can create a Microsoft Entra ID access token on behalf of the service principal. The Microsoft Entra ID access token can be used to call any Databricks REST APIs the service principal has access to, including the Tokens API, which can be used to create a Databricks personal access token for the service principal.

Create a Microsoft Entra ID access token by following these instructions:

1. Gather the following information:

   Parameter	Description
   Tenant ID	The Directory (tenant) ID for the related application registered in Microsoft Entra ID.
   Client ID	The Application (client) ID for the related application registered in Microsoft Entra ID.
   Client secret	The Value of the client secret for the related application registered in Microsoft Entra ID.

2. Use the preceding information along with curl to get the Microsoft Entra ID access token.

   curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
   https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
   -d 'client_id=<client-id>' \
   -d 'grant_type=client_credentials' \
   -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \
   -d 'client_secret=<client-secret>'
   

   Replace:

   • <tenant-id> with the registered application’s tenant ID.
   • <client-id> with the registered application’s client ID.
   • <client-secret> with the registered application’s client secret value.

   Do not change the value of the scope parameter. It represents the programmatic ID for Azure Databricks (2ff814a6-3304-4ab8-85cb-cd0e6f879c1d) along with the default scope (/.default, URL-encoded as %2f.default).

   For example:

   curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
   https://login.microsoftonline.com/a1bc2d34-5e67-8f89-01ab-c2345d6c78de/oauth2/v2.0/token \
   -d 'client_id=12a34b56-789c-0d12-e3fa-b456789c0123' \
   -d 'grant_type=client_credentials' \
   -d 'scope=2ff814a6-3304-4ab8-85cb-cd0e6f879c1d%2F.default' \
   -d 'client_secret=abc1D~Ef...2ghIJKlM3'
   

   The Microsoft Entra ID access token is in the access_token value within the output of the call.

The Microsoft Entra ID access token can be used to call the Tokens API to create a Databricks personal access token for the service principal.

Note

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