Manage service credentials
Important
This feature is in Public 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.
See also:
- For an introduction, and to learn how to create service credentials: Manage access to external cloud services using service credentials
- To learn how to reference service credentials in your code and to specify a default service credential for a compute resource: Use Unity Catalog service credentials to connect to external cloud services.
Before you begin
To perform the tasks described in this article you must meet the following requirements:
- An Azure 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 catalogCREATE SERVICE CREDENTIAL
on the metastoreACCESS
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.
Catalog Explorer
- 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).
SQL
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.
Catalog Explorer
- 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.
SQL
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:
Catalog Explorer
- 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.
SQL
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.
Catalog Explorer
- 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.
SQL
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.
Catalog Explorer
- 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.
SQL
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.
Catalog Explorer
- 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.
SQL
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>;