Manage access to Databricks automation

This article describes the how to configure permissions for Databricks credentials. To learn how to use credentials to authenticate to Databricks, see Authentication for Databricks automation.

Note

Databricks automation authentication permissions are available only in the Premium plan or above.

Personal access token permissions

Workspace admins can set permissions on personal access tokens to control which users, service principals, and groups can create and use tokens. Before you can use token access control, a Databricks workspace admin must enable personal access tokens for the workspace. See Enable or disable personal access token authentication for the workspace.

A workspace user can have one of the following token permissions:

No permissions: User cannot create or use personal access tokens to authenticate to the Databricks workspace.
Can Use: User can create a personal access token and use it to authenticate to the workspace.
Can Manage (workspace admins only): User can manage all workspace users’ personal access tokens and permission to use them. Users in the workspace admins group have this permission by default and you cannot revoke it. No other users, service principals, or groups can be granted this permission.

This table lists the permissions required for each token-related task:

Task	Can Use	Can Manage
Create a token	x	x
Use a token for authentication	x	x
Revoke your own token	x	x
Revoke any user’s or service principal’s token		x
List all tokens		x
Modify token permissions		x

Manage token permissions using the admin settings page

To manage token permissions for the workspace using the admin settings page:

Go to the admin settings page.
Click the Workspace Settings tab.
Click the Permissions button next to Personal Access Tokens to open the token permissions editor.
Search for and select the user, service principal, or group and choose the permission to assign.

If the users group has the Can Use permission and you want to apply more fine-grained access for non-admin users, remove the Can Use permission from the users group by clicking the X next to the permission drop-down in the users row.
Click + Add.
Click Save.

Warning

After you save your changes, any users who previously had either the Can Use or Can Manage permission and no longer have either permission are denied access to personal access token authentication and their active tokens are immediately deleted (revoked). Deleted tokens cannot be retrieved.

Manage token permissions using the Permissions API

Workspace admins can manage token permissions using the Permissions API.

For information on how to authenticate to Permissions API, see Authentication for Databricks automation.

Get all token permissions for the workspace

To get token permissions for all users, groups, and service principals in the workspace, call the Get tokens permissions API. (For example, GET /permissions/authorization/tokens as described in the Permissions API reference.)

The response includes an access_control_list array. Each element is a user object, a group object, or a service principal object. They each have an identity field appropriate to the type: users have a user_name field, groups have a group_name field, and service principals have a service_principal_name field. All elements have an all_permissions field that specifies which permission levels (CAN_USE or CAN_MANAGE) are granted.

For example:

curl -n -X GET "https://<databricks-instance>/api/2.0/preview/permissions/authorization/tokens"

Example response:

{
  "object_id": "authorization/tokens",
  "object_type": "tokens",
  "access_control_list": [
    {
      "user_name": "jsmith@example.com",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        }
      ]
    }
  ]
}

Set token permissions

To set token permissions, call the Update token permissions API (PATCH /permissions/authorization/tokens).

You can set permissions on one or more users, groups, or service principals. For each user, you need to know the email address, which is specified in the user_name request property. For each group, specify the group name in the group_name property. For a service principal, specify the service principal applicationId value in the service_principal_name property.

You can only grant, not revoke, permissions with this API.

For example, the following example grants access to user jsmith@example.com and the group mygroup.

curl -n -X PATCH "https://<databricks-instance>/api/2.0/preview/permissions/authorization/tokens" \
  -d '{
    "access_control_list": [
      {
        "user_name": "jsmith@example.com",
        "permission_level": "CAN_USE",
      },
      {
        "group_name": "mygroup",
        "permission_level": "CAN_USE",
      }
    ]
  }'

Example response:

{
  "access_control_list": [
    {
      "user_name": "jsmith@example.com",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        }
      ]
    },
    {
      "group_name": "mygroup",
      "all_permissions": [
        {
          "permission_level": "CAN_USE",
          "inherited": false
        }
      ]
    }
  ]
}

If you want to set token permissions for all members in the workspace in one request, use the Replace all token permissions for workspace API (PUT /permissions/authorization/tokens).

Remove permissions

To revoke permissions from all or some non-admin users, use the Replace all token permissions for workspace API (PUT /permissions/authorization/tokens), which requires that you specify the complete set of permissions for all objects that are granted permissions for the entire workspace.

The following example grants the Can Use permission to group field-automation-group, omits permissions for the users (all users) group, and grants Can Manage permission to the admins group as required by the API. Any non-admin users that are not in the group field-support-engineers will lose access to token creation and their existing tokens are immediately deleted (revoked).

curl -n -X PUT "https://<databricks-instance>/api/2.0/preview/permissions/authorization/tokens" \
  -d '{
    "access_control_list": [
      {
        "group_name": "field-automation-group",
        "permission_level": "CAN_USE",
      },
      {
        "group_name": "admins",
        "permission_level": "CAN_MANAGE",
      },
    ]
  }'

Terraform integration

You can manage token permissions in a fully automated setup using Databricks Terraform provider and databricks_permissions as follows.

Warning

The following configuration contains the statement authorization = "tokens". There can be only one authorization = "tokens" permissions resource per Databricks workspace, otherwise there will be a permanent configuration drift. After applying the following changes, users who previously had either CAN_USE or CAN_MANAGE permission but no longer have either permission have their access to personal access token authentication revoked. Their active tokens are immediately deleted (revoked).

resource "databricks_group" "auto" {
  display_name = "Automation"
}

resource "databricks_group" "eng" {
  display_name = "Engineering"
}

resource "databricks_permissions" "token_usage" {
  authorization = "tokens"

  access_control {
    group_name       = databricks_group.auto.display_name
    permission_level = "CAN_USE"
  }

  access_control {
    group_name       = databricks_group.eng.display_name
    permission_level = "CAN_USE"
  }
}

Password permissions

When unified login is disabled, by default all workspace admin users can sign in to Databricks using either workspace-level SSO or their username and password, and all API users can authenticate to the Databricks REST APIs using their username and password.

As a workspace admin, when workspace-level SSO is enabled you can configure password access control to limit workspace admin users’ and API users’ ability to authenticate with their username and password.

Note

Password access control can only be configured when unified login is disabled. Unified login is enabled for all accounts created after June 21, 2023. If unified login is enabled on your account and you require password access control, contact your Databricks representative.

For more information on the sign-in process when unified login is enabled, see Workspace sign-in process.

There are two permission levels for passwords: No permissions and Can Use. Can Use grants more abilities to workspace admins than to non-admin users. This table lists the abilities for each permission.

Task	No permissions	Can Use
Can authenticate to the API using password		x
Can authenticate to the Databricks UI using password		x (Workspace admins only)

If a non-admin user with no permissions attempts to make a REST API call using a password, authentication will fail. Databricks recommends personal access token REST authentication instead of username and password.

Workspace admin users with Can Use permission see the Admin Log In tab on the sign-in page. They can choose to use that tab to log in to Databricks with username and password.

Workspace admins with no permissions do not see this page and must log in using SSO. When workspace-level SSO is enabled, all non-admin users do not see this page and must log in using SSO.

Configure password permissions

This section describes how to manage permissions using the workspace admin settings page.

As a workspace admin, log in to the Databricks workspace.
Click your username in the top bar of the Databricks workspace and select Admin Settings.
Click the Workspace Settings tab.
Next to Password Usage, click Permission Settings.
In the Permissions Settings dialog, assign password permission to users and groups using the drop-down menu next to the user or group. You can also configure permissions for the Admins group.
Click Save.

You can also configure password permissions using the Permissions API.