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

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. 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 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 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 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 using the workspace-level SCIM APIs.

Account admins can manage service principals using the following interfaces:

Workspace admins can manage service principals in their workspace using the following interfaces:

For more information about how account-level identities work with workspaces, see Manage users, service principals, and groups.

For more information about service principals and how to use them, see Service principals for Azure Databricks automation.

Add a service principal to your Azure Databricks account

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

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

  1. Sign in to the Azure portal.

    Note

    The portal to use is different depending on whether your Azure AD 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 Azure Active Directory.

  4. Within Manage, click App registrations > New 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.

    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

    Azure registered app overview

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

To use service principals, you must generate Azure AD tokens for them. See Get Azure AD tokens for service principals.

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

Account admins can add and manage service principals in the Azure 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.azuredatabricks.net/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.

  3. Assign the service principal to a workspace using the Workspace Assignment 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.

You can also assign the account admin role using the SCIM API 2.0 (Accounts). To use service principals, you must generate Azure AD tokens for them. See Get Azure AD tokens for service principals.

Remove service principals from your Azure Databricks account

Account admins can delete service principals from a 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 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

Account admins can add service principals to identity-federated workspaces using the following:

  • The account console
  • The Workspace Assignment API

Workspace admins can manage service principals in their workspace using the following:

  • The workspace admin console (if the workspace is enabled for identity federation)
  • The workspace-level SCIM (ServicePrincipals) API
  • The Workspace Assignment API (if the workspace is enabled for identity federation)

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 Workspace Icon 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 Azure Databricks workspace.

  2. Click your username in the top bar of the Azure 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 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 or use the admin console to create a new service principal.

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:

Remove a service principal from a workspace

Account admins can remove service principals from identity-federated workspaces using the following:

  • The account console

    • The Workspace Assignment API

    Workspace admins can remove service principals from their workspace using the following:

    • The workspace admin console (if the workspace is enabled for identity federation)
    • The workspace-level SCIM (ServicePrincipals) API
    • The Workspace Assignment API (if the workspace is enabled for identity federation)

    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 Workspace Icon Workspaces.
    2. On the Permissions tab, find the service principal.
    3. Click the Kebab menu 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 Azure Databricks workspace.

    2. Click your username in the top bar of the Azure Databricks workspace and select Admin Console.

    3. On the Service principals tab, find the service principal and click the Remove User Icon 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:

Manage access tokens for a service principal

To authenticate a service principal to APIs on Azure Databricks, an administrator can create an Azure AD access token on behalf of the service principal. The Azure AD access token can be used to call Databricks REST APIs. Create an Azure AD access token by following these instructions:

  1. Gather the following information:

    Parameter Description
    Tenant ID The Directory (tenant) ID for the application registered in Azure AD.
    Client ID The Application (client) ID for the application registered in Azure AD.
    Client secret The Value of the client secret for the application registered in Azure AD.
  2. Use the preceding information along with curl to get the Azure AD 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 Azure AD access token is in the access_token value within the output of the call.

For additional, detailed step-by-step instructions for creating access tokens for service principals, see Service principals for Azure Databricks automation.

Note

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

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