Manage storage credentials

This page describes how to list, view, update, grant permissions on, and delete storage credentials.

Databricks recommends that you grant only CREATE EXTERNAL LOCATION and no other privileges on storage credentials.

This page describes how to manage storage credentials using Catalog Explorer and SQL commands. For information about using the Databricks CLI or Terraform instead, see the Databricks Terraform documentation and What is the Databricks CLI?.

List storage credentials

To view the list of all storage credentials in a metastore, you can use Catalog Explorer or a SQL command.

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Sort the credentials by Purpose (STORAGE or SERVICE).

SQL

Run the following command in a notebook or the Databricks SQL editor.

SQL

SHOW STORAGE CREDENTIALS;

View a storage credential

To view the properties of a storage credential, you can use Catalog Explorer or a SQL command.

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Click the name of a storage credential to see its properties.

SQL

Run the following command in a notebook or the Databricks SQL editor. Replace <credential-name> with the name of the credential.

SQL

DESCRIBE STORAGE CREDENTIAL <credential-name>;

Assign a storage credential to specific workspaces

By default, a storage credential is accessible from all of the workspaces in the metastore. This means that if a user has been granted a privilege (such as CREATE EXTERNAL LOCATION) on that storage credential, they can exercise that privilege from any workspace attached to the metastore. If you use workspaces to isolate user data access, you may want to allow access to a storage credential only from specific workspaces. This feature is known as workspace binding or storage credential isolation.

A typical use case for binding a storage credential to specific workspaces is the scenario in which a cloud admin configures a storage credential using a production cloud account credential, and you want to ensure that Databricks users use this credential to create external locations only in the production workspace.

For more information about workspace binding, see Limit catalog access to specific workspaces.

note

Workspace bindings are referenced when privileges against storage credentials are exercised. For example, if a user creates an external location using a storage credential, the workspace binding on the storage credential is checked only when the external location is created. After the external location is created, it will function independently of the workspace bindings configured on the storage credential.

Bind a storage credential to one or more workspaces

To assign a storage credential to specific workspaces, you can use Catalog Explorer or the Databricks CLI.

Permissions required: Metastore admin, storage credential owner, or MANAGE on the storage credential.

note

Metastore admins can see all storage credentials in a metastore using Catalog Explorer—and storage credential owners can see all storage credentials that they own in a metastore—regardless of whether the storage credential is assigned to the current workspace. Storage credentials that are not assigned to the workspace appear grayed out.

Catalog Explorer

1. Log in to a workspace that is linked to the metastore.

2. In the sidebar, click Catalog.

3. On the Quick access page, click the External data > button and go to the Credentials tab.

4. Select the storage credential and go to the Workspaces tab.

5. On the Workspaces tab, clear the All workspaces have access checkbox.

   If your storage credential is already bound to one or more workspaces, this checkbox is already cleared.

6. Click Assign to workspaces and enter or find the workspaces you want to assign.

To revoke access, go to the Workspaces tab, select the workspace, and click Revoke. To allow access from all workspaces, select the All workspaces have access checkbox.

CLI

There are two Databricks CLI command groups and two steps required to assign a storage credential to a workspace.

In the following examples, replace <profile-name> with the name of your Databricks authentication configuration profile. It should include the value of a personal access token, in addition to the workspace instance name and workspace ID of the workspace where you generated the personal access token. See Personal access token authentication (deprecated).

1. Use the storage-credentials command group's update command to set the storage credential's isolation mode to ISOLATED:

   Bash

   databricks storage-credentials update <my-storage-credential> \
   --isolation-mode ISOLATED \
   --profile <profile-name>

   The default isolation-mode is OPEN to all workspaces attached to the metastore.

2. Use the workspace-bindings command group's update-bindings command to assign the workspaces to the storage credential:

   Bash

   databricks workspace-bindings update-bindings storage-credential <my-storage-credential> \
   --json '{
     "add": [{"workspace_id": <workspace-id>}...],
     "remove": [{"workspace_id": <workspace-id>}...]
   }' --profile <profile-name>

   Use the "add" and "remove" properties to add or remove workspace bindings.

   note

   Read-only binding (BINDING_TYPE_READ_ONLY) is not available for storage credentials. Therefore there is no reason to set binding_type for the storage credentials binding.

To list all workspace assignments for a storage credential, use the workspace-bindings command group's get-bindings command:

Bash

databricks workspace-bindings get-bindings storage-credential <my-storage-credential> \
--profile <profile-name>

Unbind a storage credential from a workspace

Instructions for revoking workspace access to a storage credential using Catalog Explorer or the workspace-bindings CLI command group are included in Bind a storage credential to one or more workspaces.

Show grants on a storage credential

To view the grants on a storage credential, you can use Catalog Explorer or a SQL command.

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Click the name of a storage credential.
4. Click Permissions.

SQL

To show grants on a storage credential, use a command like the following. You can optionally filter the results to show only the grants for the specified principal.

SQL

SHOW GRANTS [<principal>] ON STORAGE CREDENTIAL <storage-credential-name>;

Replace the placeholder values:

• <principal>: The email address of the account-level user or the name of the account level group to whom to grant the permission. If a group or username contains a space or @ symbol, use back-ticks around it (not apostrophes). For example finance team .
• <storage-credential-name>: The name of a storage credential.

Grant permissions to create external locations

To grant permission to create an external location using a storage credential, complete the following steps:

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Click the name of a storage credential to open the details page.
4. Click Permissions.
5. To grant permission to users or groups, select each identity, then click Grant.
6. To revoke permissions from users or groups, select each identity, then click Revoke.

SQL

Run the following command in a notebook or the SQL query editor:

SQL

GRANT CREATE EXTERNAL LOCATION ON STORAGE CREDENTIAL <storage-credential-name> TO <principal>;

Replace the placeholder values:

• <principal>: The email address of the account-level user or the name of the account level group to whom to grant the permission. If a group or username contains a space or @ symbol, use back-ticks around it (not apostrophes). For example finance team .
• <storage-credential-name>: The name of a storage credential.

Change the owner of a storage credential

A storage credential's creator is its initial owner. To change the owner to a different account-level user or group, you can use Catalog Explorer or a SQL command.

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Click the name of a storage credential.
4. Click next to Owner.
5. Type to search for a principal and select it.
6. Click Save.

SQL

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

• <credential-name>: The name of the credential.
• <principal>: The email address of an account-level user or the name of an account-level group.

SQL

ALTER STORAGE CREDENTIAL <credential-name> OWNER TO <principal>;

Mark a storage credential as read-only

If you want users to have read-only access to all data managed by a storage credential, you can use Catalog Explorer to mark the storage credential as read-only.

Making storage credentials read-only means that any storage configured with that credential is read-only.

You can mark storage credentials as read-only when you create them.

You can also use Catalog Explorer to change read-only status after creating a storage credential:

1. In Catalog Explorer, find the storage credential, click the kebab menu on the object row, and select Edit.
2. On the edit dialog, select the Read only option.

Rename a storage credential

To rename a storage credential, you can use Catalog Explorer or a SQL command.

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Click the name of a storage credential to open the edit dialog.
4. Rename the storage credential and save it.

SQL

Run the following command in a notebook or the Databricks SQL editor. Replace the placeholder values:

• <credential-name>: The name of the credential.
• <new-credential-name>: A new name for the credential.

SQL

ALTER STORAGE CREDENTIAL <credential-name> RENAME TO <new-credential-name>;

Delete a storage credential

To delete (drop) a storage credential you must be its owner. To delete a storage credential, you can use Catalog Explorer or a SQL command.

Catalog Explorer

1. In the sidebar, click Catalog.
2. On the Quick access page, click the External data > button and go to the Credentials tab.
3. Click the name of a storage credential to open the edit dialog.
4. Click the Delete button.

SQL

Run the following command in a notebook or the Databricks SQL editor. Replace <credential-name> with the name of the credential. Portions of the command that are in brackets are optional. By default, if the credential is used by an external location, it is not deleted. Replace <credential-name> with the name of the credential.

IF EXISTS does not return an error if the credential does not exist.

SQL

DROP STORAGE CREDENTIAL [IF EXISTS] <credential-name>;