Manage service credentials

Preview

This article describes how to list, view, update, grant permissions on, and delete service credentials, which are Unity Catalog securable objects that let you govern access to external cloud services.

Before you begin

To perform the tasks described in this article you must meet the following requirements:

A Databricks workspace enabled for Unity Catalog.
To list or view a service credential, you must have one of the following privileges or roles:
- BROWSE privilege on the parent catalog
- CREATE SERVICE CREDENTIAL on the metastore
- ACCESS on the service credential
- Owner of the service credential
- Metastore admin
To perform any of the other tasks listed in this article, you must be the owner of the service credential or a metastore admin.
If you use SQL commands to list, view, or update the service credential, you need compute on Databricks Runtime 15.4 LTS or above. There is no Databricks Runtime version requirement if you use Catalog Explorer or the REST API.

List service credentials

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

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

Run the following command in a notebook.

SHOW SERVICE CREDENTIALS;

View a service credential

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

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

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

DESCRIBE SERVICE CREDENTIAL <credential-name>;

Show grants on a service credential

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

SHOW GRANTS [<principal>] ON SERVICE CREDENTIAL <service-credential-name>;

Replace the placeholder values:

<principal>: The email address of the account-level user or the name of the account level group who was granted the permission.
<service-credential-name>: The name of a service credential.

Note

If a group or username contains a space or @ symbol, use back-ticks around it (not apostrophes). For example finance team` `.

Grant permissions to use a service credential to access an external cloud service

To grant permission to use a service credential to access an external cloud service, complete the following steps. You can use Catalog Explorer or SQL commands:

In the sidebar, click Catalog.
On the Quick access page, click the External data > button and go to the Credentials tab.
Click the name of a service credential to open the details page.
Click Permissions.
To grant permission to users or groups, select each identity, then click Grant.
- Select ACCESS to grant the ability to use the service credential to access an external cloud service or services.
- Select CREATE CONNECTION to grant the ability to create a Lakehouse Federation connection in Unity Catalog using this service credential. See Manage connections for Lakehouse Federation.
To revoke permissions from users or groups, select each identity, then click Revoke.

To grant access, run one of the following commands in a notebook, replacing 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.
<service-credential-name>: The name of a service credential.

Note

If a group or username contains a space, dash (-), or @ symbol, use back-ticks around it (not apostrophes). For example, `finance team`.

GRANT ACCESS ON SERVICE CREDENTIAL <service-credential-name> TO <principal>;

If you want to grant the ability to create a Lakehouse Federation connection in Unity Catalog using this service credential, use the following:

GRANT CREATE CONNECTION ON SERVICE CREDENTIAL <service-credential-name> TO <principal>;

To revoke access, replace GRANT with REVOKE in these examples.

Change the owner of a service credential

A service 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.

In the sidebar, click Catalog.
On the Quick access page, click the External data > button and go to the Credentials tab.
Click the name of a service credential to open the edit dialog.
Click next to Owner.
Type to search for a principal and select it.
Click Save.

Run the following command in a notebook. 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.

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

Rename a service credential

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

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

Run the following command in a notebook. Replace the placeholder values:

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

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

Delete a service credential

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

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

Run the following command in a notebook. Replace <credential-name> with the name of the credential. Portions of the command that are in brackets are optional.

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

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