Secret access control

By default, all users in all pricing plans can create secrets and secret scopes. Using secret access control, available with the Premium plan or above, you can configure fine-grained permissions for managing access control. This guide describes how to set up these controls.

Note

  • Access control is available only in the Premium plan or above. If your account does not include that plan, you must explicitly grant MANAGE permission to the “users” (all users) group when you create secret scopes.

Secret access control

Access control for secrets is managed at the secret scope level. An access control list (ACL) defines a relationship between a Databricks principal (user, service principal or group), secret scope, and permission level. In general, a user will use the most powerful permission available to them (see Permission Levels).

When a secret is read via a notebook using the Secrets utility (dbutils.secrets), the user’s permission will be applied based on who is executing the command, and they must at least have READ permission.

When a scope is created, an initial MANAGE permission level ACL is applied to the scope. Subsequent access control configurations can be performed by that principal.

Permission levels

The secret access permissions are as follows:

  • MANAGE - Allowed to change ACLs, and read and write to this secret scope.

  • WRITE - Allowed to read and write to this secret scope.

  • READ - Allowed to read this secret scope and list what secrets are available.

Each permission level is a subset of the previous level’s permissions (that is, a principal with WRITE permission for a given scope can perform all actions that require READ permission).

Note

Databricks admins have MANAGE permissions to all secret scopes in the workspace.

Create a secret ACL

To create a secret ACL for a given secret scope using the Databricks CLI (legacy) (version 0.7.1 and above):

databricks secrets put-acl --scope <scope-name> --principal <principal> --permission <permission>

Making a put request for a principal that already has an applied permission overwrites the existing permission level.

The principal field specifies an existing Databricks principal. A user is specified using their email address, a service principal using its applicationId value, and a group using its group name.

View secret ACLs

To view all secret ACLs for a given secret scope:

databricks secrets list-acls --scope <scope-name>

To get the secret ACL applied to a principal for a given secret scope:

databricks secrets get-acl --scope <scope-name> --principal <principal>

If no ACL exists for the given principal and scope, this request will fail.

Delete a secret ACL

To delete a secret ACL applied to a principal for a given secret scope:

databricks secrets delete-acl --scope <scope-name> --principal <principal>

Terraform integration

You can manage permissions in a fully automated setup using Databricks Terraform provider and databricks_secret_acl:

resource "databricks_group" "ds" {
  display_name = "data-scientists"
}

resource "databricks_secret_scope" "app" {
  name = "app-secret-scope"
}

resource "databricks_secret_acl" "my_secret_acl" {
  principal = databricks_group.ds.display_name
  permission = "READ"
  scope = databricks_secret_scope.app.name
}

resource "databricks_secret" "publishing_api" {
  key = "publishing_api"
  string_value = "SECRET_API_TOKEN_HERE"
  scope = databricks_secret_scope.app.name
}