Roles for managing service principals

This article describes how to manage roles on service principals in your Databricks account.

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.

You can grant Databricks users, service principals, and account groups access 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.

For an overview of service principals see Manage service principals.

Service principal roles

Service principal roles are account-level roles. This means that they only need to be defined once, in your account, and apply across all workspaces. There are two roles that you can grant on a service principal: Service Principal Manager and Service Principal User.

  • Service Principal Manager allows you to manage roles on a service principal. The creator of a service principal has the Service Principal Manager role on the service principal. Account admins have the Service Principal Manager role on all service principals in an account.

Note

If a service principal was created before June 13, 2023, the creator of the service principal does not have the Service Principal Manager role by default. If you need to be a manager, ask an account admin to grant you the Service Principal Manager role.

  • Service Principal User allows workspace users to run jobs as the service principal. The job will run with the identity of the service principal, instead of the identity of the job owner. The Service Principal User role also allows workspace admins to create personal access tokens on behalf of the service principal. Creating OAuth secrets for a service principal requires the account admin or workspace admin role.

Note

When the RestrictWorkspaceAdmins setting on a workspace is set to ALLOW ALL, workspace admins can create a personal access token on behalf of any service principal in their workspace. To enforce the Service Principal User role for workspace admins to create a personal access token for a service principal, see Restrict workspace admins.

Users with the Service Principal Manager role do not inherit the Service Principal User role. If you want to use the service principal to execute jobs, you need to explicitly assign yourself the service principal user role, even after creating the service principal.

Manage service principal roles using the account console

Account admins can manage service principals roles using the account console.

View roles on 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 name.

  4. Click the Permissions tab.

You can see the list of principals and the roles that they are granted on the service principal. You can also use the search bar to search for a specific principal or role.

Grant roles on 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 name.

  4. Click the Permissions tab.

  5. Click Grant access.

  6. Search for and select the user, service principal, or group and choose the role or roles (Service principal: Manager or Service principal: User) to assign.

    Note

    Users with the Service Principal Manager role do not inherit the Service Principal User role. If you want the user to use the service principal to execute jobs, you will need to explicitly assign the Service Principal User role.

  7. Click Save.

Revoke roles on 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 name.

  4. Click the Permissions tab.

  5. Search for the user, service principal, or group to edit their roles.

  6. On the row with the principal, click the kebab menu Kebab menu and then select Edit. Alternatively, select Delete to revoke all of the roles for the principal.

  7. Click Edit.

  8. Click the X next to the roles that you want to revoke.

  9. Click Save.

Manage service principal roles using the workspace admin settings page

Workspace admins can manage service principals roles for service principals that they have the Service Principal Manager role on using the admin settings page.

View roles on a service principal

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

  3. Click on the Identity and access tab.

  4. Next to Service principals, click Manage.

  5. Find and click the name.

  6. Click the Permissions tab.

You can see the list of principals and the roles that they are granted on the service principal. You can also use the search bar to search for a specific principal or role.

Grant roles on a service principal

You must have the Service Principal Manager role on a service principal in order to grant roles.

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

  3. Click on the Identity and access tab.

  4. Next to Service principals, click Manage.

  5. Find and click the name.

  6. Click the Permissions tab.

  7. Click Grant access.

  8. Search for and select the user, service principal, or group and choose the role or roles (Service principal: Manager or Service principal: User) to assign.

    Note

    Roles can be granted to any account-level user, service principal, or group, even if they are not a member of the workspace. Roles cannot be granted to workspace-local groups.

    Users with the Service Principal Manager role do not inherit the Service Principal User role. If you want the user to use the service principal to execute jobs, you will need to explicitly assign the Service Principal User role.

  9. Click Save.

Revoke roles on a service principal

You must have the Service Principal Manager role on a service principal in order to revoke roles.

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

  3. Click on the Identity and access tab.

  4. Next to Service principals, click Manage.

  5. Find and click the name.

  6. Click the Permissions tab.

  7. Search for the user, service principal, or group to edit their roles.

  8. On the row with the principal, click the kebab menu Kebab menu and then select Edit. Alternatively, select Delete to revoke all of the roles for the principal.

  9. Click Edit.

  10. Click the X next to the roles that you want to revoke.

  11. Click Save.

Manage service principal roles using the Databricks CLI

You must have the Service Principal Manager role to manage roles on a service principal. You can use the Databricks CLI to manage roles. For information on installing and authenticating to the Databricks CLI, see What is the Databricks CLI?.

You can also manage service principal roles using the Accounts Access Control API. The Accounts Access Control API is supported through the Databricks account and workspaces.

Account admins call the API on accounts.cloud.databricks.com ({account-domain}/api/2.0/preview/accounts/{account_id}/access-control).

Users with the Service Principal Manager role that are not account admins call the API on the workspace domain ({workspace-domain}/api/2.0/preview/accounts/access-control/).

Grant roles on a service principal using the Databricks CLI

The Accounts Access Control API and CLI uses an etag field to ensure consistency. To grant or revoke service principal roles through the API, first issue a GET rule set command and receive an etag in response. You can then apply changes locally, and finally issue a PUT rule set with the etag.

For example, issue a GET rule set on the service principal that you want to grant access to by running the following command:

databricks account access-control get-rule-set accounts/<account-id>/servicePrincipals/<application-id>/ruleSets/default <etag>

Replace:

  • <account-id> with the account ID.

  • <application-id> with the service principal application ID.

  • <etag> with “”

Example response:

{
  "etag":"<etag>",
  "grant_rules": [
    {
      "principals": [
        "users/user@example.com"
      ],
      "role":"roles/servicePrincipal.manager"
    },
    {
      "principals": [
        "users/user@example.com"
      ],
      "role":"roles/servicePrincipal.user"
    }
  ],
  "name":"<name>"
}

Copy the etag field from the response body for later use.

Then, you can make updates locally when you decide on the final state of the rules and then update the rule set using the etag. To grant the Service principal: User role to the user user2@example.com, run the following:

databricks account access-control update-rule-set --json '{
  "name": "accounts/<account-id>/servicePrincipals/<application-id>/ruleSets/default",
  "rule_set": {
      "name": "accounts/<account-id>/servicePrincipals/<application-id>/ruleSets/default",
      "grant_rules": [
        {
            "role": "roles/servicePrincipal.user",
            "principals": ["users/user2@example.com"]
        }
      ],
      "etag": "<etag>"
  }
}'

Replace:

  • <account-id> with the account ID.

  • <application-id> with the service principal application ID.

  • <etag> with the etag that you copied from the last response.

Example response:

{
  "etag":"<new-etag>",
  "grant_rules": [
    {
      "principals": [
        "users/user2@example.com"
      ],
      "role":"roles/servicePrincipal.user"
    }
  ],
  "name":"accounts/<account-id>/servicePrincipals/<application-id>/ruleSets/default"
}

Important

Because this is a PUT method, all existing roles are overwritten. To keep any existing roles, you must add them to the grant_roles array.

List the service principals that you can use

Using the Workspace Service Principals API, you can list the service principals that you have the user role on by filtering on servicePrincipal/use.

To list the service principals that you have the Service Principal User role on, run the following command:

databricks service-principals list -p WORKSPACE --filter "permission eq 'servicePrincipal/use'"

You can also list service principals using the Workspace Service Principals API.