Secret Scopes

Managing secrets begins with creating a secret scope. A secret scope is identified by its name, unique within a workspace. The names are considered non-sensitive and are readable by all users in the workspace. A workspace is limited to a maximum of 100 scopes.

Overview

A secret scope is stored in (backed by) a Databricks database. You create a secret scope using the Databricks CLI (version 0.7.1 and above). Alternatively, you can use the Secrets API.

Scope permissions

Scopes are created with permissions controlled by ACLs. By default, scopes are created with MANAGE permission for the user who created the scope (the “creator”), which lets the creator read secrets in the scope, write secrets to the scope, and change ACLs for the scope. If your account has the Databricks Operational Security Package, you can assign granular permissions at any time after you create the scope. For details, see Secret Access Control.

You can also override the default and explicitly grant MANAGE permission to all users when you create the scope. In fact, you must do this if your account does not have the Databricks Operational Security Package. See the instructions in this topic for details.

Create a Databricks-backed secret scope

To create a scope using the Databricks CLI:

databricks secrets create-scope --scope <scope-name>

By default, scopes are created with MANAGE permission for the user who created the scope. If your account does not have the Databricks Operational Security Package, you must override that default and explicitly grant the MANAGE permission to “users” (all users) when you create the scope:

databricks secrets create-scope --scope <scope-name> --initial-manage-principal users

If your account has the Databricks Operational Security Package, you can change permissions at any time after you create the scope. For details, see Secret Access Control.

Once you have created a Databricks-backed secret scope, you can add secrets.

List secret scopes

To list the existing scopes in a workspace:

databricks secrets list-scopes

Delete a secret scope

Deleting a secret scope deletes all secrets and ACLs applied to the scope. To delete a scope:

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