Use Unity Catalog service credentials to connect to external cloud services

Preview

This feature is in Public Preview.

This article describes how to use a service credential in Unity Catalog to connect to external cloud services. A service credential object in Unity Catalog encapsulates a long-term cloud credential that provides access to an external cloud service that users need to connect to from Databricks.

See also:

Before you begin

Before you can use a service credential to connect to an external cloud service, you must have:

  • A Databricks workspace that is enabled for Unity Catalog.

  • A compute resource that is on Databricks Runtime 15.4 LTS or above. SQL warehouses are not supported.

  • A service credential created in your Unity Catalog metastore that gives access to the cloud service.

  • The ACCESS privilege on the service credential or ownership of the service credential.

Use a service credential in your code

This section provides an example of using a service credential in a notebook. Only Python is supported during the public preview. Replace placeholder values.

Example: configure a boto3 session to use a specific service credential 

import boto3
boto3_session = boto3.Session(botocore_session=dbutils.credentials.getServiceCredentialsProvider('your-service-credential'), region_name='your-aws-region')
sm = boto3_session.client('secretsmanager')

Specify a default service credential for a compute resource

You can optionally specify a default service credential for an all-purpose or jobs compute cluster by setting an environment variable. By default, the SDK uses that service credential if no authentication is provided. Users still require ACCESS on that service credential to connect to the external cloud service. Databricks does not recommend this approach, because it makes your code less portable than naming the service credential in your code.

Note

Service credentials are not supported on serverless compute or SQL warehouses.

  1. Open the edit page for the cluster.

    See Manage compute.

  2. Click Advanced options at the bottom of the page and go to the Spark tab.

  3. Add the following entry in Environment variables, replacing <your-service-credential>:

    DATABRICKS_DEFAULT_SERVICE_CREDENTIAL_NAME=<your-service-credential>

The following code sample does not specify a service credential. Instead, it uses the service credential specified in the DATABRICKS_DEFAULT_SERVICE_CREDENTIAL_NAME environment variable:

import boto3
sm = boto3.client('secretsmanager', region_name='your-aws-region')

Compare to the example in Example: configure a boto3 session to use a specific service credential, which adds the credential specification:

boto3_session = boto3.Session(botocore_session=dbutils.credentials.getServiceCredentialsProvider('your-service-credential'), region_name='your-aws-region')