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.
This article describes how to manage secret access control using the Databricks CLI (legacy) (version 0.7.1 and above). Alternatively, you can use the Secrets API.
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
}