Create a recipient object for non-Databricks users using bearer tokens (open sharing)

This article describes how to create Delta Sharing recipients who do not have access to a Unity Catalog-enabled Databricks workspace and grant those recipients access to securely shared data using bearer tokens. This authentication flow, along with the OIDC token federation authentication flow, is called open sharing.

Here’s how it works:

1. As a data provider, you create the recipient object in your Unity Catalog metastore.

2. When you create the recipient object, you select the bearer token method, Azure Databricks generates a token, a credential file that includes the token, and an activation link for you to share with the recipient.

   The recipient object has the authentication type of TOKEN. You can refresh and revoke the token as needed.

3. The recipient accesses the activation link, downloads the credential file, and uses the credential file to authenticate and get read access to the tables you include in the shares that you give them access to.

The OIDC federation flow is an alternative to the bearer token flow described in this article. It has advantages of security and convenience over the bearer token flow. For details, see Use Open ID Connect (OIDC) federation to enable authentication to Delta Sharing shares (open sharing).

Create the recipient

To create a recipient for open sharing, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the CREATE RECIPIENT SQL command in an Azure Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or user with the CREATE_RECIPIENT privilege for the Unity Catalog metastore where the data you want to share is registered.

Catalog Explorer

1. In your Azure Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click New recipient.

4. Enter the Recipient name

5. For Recipient type, select Open.

6. Select Token.

7. (Optional) Set the Token lifetime expiration time (in seconds, minutes, hours, or day from recipient creation time). Leave Set expiration selected to set an expiration time. Clear the selection to allow the token to live indefinitely.

   If you select Set expiration and leave the field blank, the token lifetime defaults to the recipient token lifetime value set in the metastore configuration. See Modify the recipient token lifetime. For information about changing the token lifetime and rotating tokens, see Manage recipient tokens.

8. (Optional) Enter a comment.

9. Click Create.

10. Copy the activation link.

    Alternatively, you can get the activation link later. See Get the activation link.

11. (Optional) Create custom Recipient properties.

    On the recipient Overview tab, click the edit icon next to Recipient properties. Then add a property name (Key) and Value. For details, see Manage recipient properties.

SQL

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

CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[COMMENT "<comment>"];

You can also add custom properties for the recipient. For details, see Manage recipient properties.

CLI

Run the following command using the Databricks CLI.

databricks recipients create <recipient-name>

You can also add custom properties for the recipient. For details, see Manage recipient properties.

Output includes the activation_url that you share with the recipient.

The recipient is created with the authentication_type of TOKEN.

Get the activation link

To get the new recipient’s activation link, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the DESCRIBE RECIPIENT SQL command in an Azure Databricks notebook or the Databricks SQL query editor.

If the recipient has already downloaded the credential file, the activation link is not returned or displayed.

Permissions required: Metastore admin, user with the USE RECIPIENT privilege, or the recipient object owner.

Catalog Explorer

1. In your Azure Databricks workspace, click Catalog.

2. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

3. On the Shared by me tab, click Recipients, and select the recipient.

4. On the recipient details page, copy the Activation link.

SQL

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

DESCRIBE RECIPIENT <recipient-name>;

Output includes the activation_link.

CLI

Run the following command using the Databricks CLI.

databricks recipients get <recipient-name>

Output includes the activation_url.

Grant the recipient access to a share

Once you’ve created the recipient and created shares, you can grant the recipient access to those shares.

To grant share access to recipients, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the GRANT ON SHARE SQL command in an Azure Databricks notebook or the Databricks SQL query editor.

Permissions required: One of the following:

• Metastore admin.
• Delegated permissions or ownership on both the share and the recipient objects ((USE SHARE + SET SHARE PERMISSION) or share owner) AND (USE RECIPIENT or recipient owner).

For instructions, see Manage access to Delta Sharing data shares (for providers).

Send the recipient their connection information

You must let the recipient know how to access the data that you are sharing with them. Use a secure channel to share the activation link and a link to instructions for using it.

You can download the credential file only once. Recipients should treat the downloaded credential as a secret and must not share it outside of their organization. If you have concerns that a credential may have been handled insecurely, you can rotate a recipient’s credential at any time. For more information about managing credentials to ensure secure recipient access, see Security considerations for tokens.

Manage recipient tokens

If you are sharing data with a recipient using the open sharing bearer token flow, you may need to rotate that recipient’s token. Rotating a token consists of setting an existing token to expire and replacing it with a new token and activation URL.

You should rotate a recipient’s token and generate a new activation URL in the following circumstances:

• When the existing recipient token is about to expire.
• If a recipient loses their activation URL or if it is compromised.
• If the credential is corrupted, lost, or compromised after it is downloaded by a recipient.
• When you modify the recipient token lifetime for a metastore. See Modify the recipient token lifetime.

Security considerations for tokens

At any given time, a recipient can have at most two tokens: an active token and a rotated token. The rotated token is one that has been set to expire and be replaced by the active token. Until the rotated token expires, attempting to rotate the token again results in an error.

When you rotate a recipient’s token, you can optionally set --existing-token-expire-in-seconds to the number of seconds before the existing recipient token—that is, the one to be rotated—expires. If you set the value to 0, the existing recipient token expires immediately.

Databricks recommends that you set --existing-token-expire-in-seconds to a relatively short period that gives the recipient organization time to access the new activation URL while minimizing the amount of time that the recipient has two active tokens. If you suspect that the existing recipient token is compromised, Databricks recommends that you force it to expire immediately.

If a recipient’s existing activation URL has never been accessed, rotating the existing token invalidates that activation URL and replaces it with a new one.

If all recipient tokens have expired, rotating the token replaces the existing activation URL with a new one. Databricks recommends that you promptly rotate or drop a recipient whose token has expired.

If a recipient activation URL is inadvertently sent to the wrong person or is sent over an insecure channel, Databricks recommends that you:

1. Revoke the recipient’s access to the share.
2. Rotate the recipient and set --existing-token-expire-in-seconds to 0.
3. Share the new activation URL with the intended recipient over a secure channel.
4. After the activation URL has been accessed, grant the recipient access to the share again.

In extreme situations, instead of rotating the recipient’s token, you can drop and re-create the recipient.

Rotate a recipient’s token

To rotate a recipient’s token, you can use Catalog Explorer or the Databricks Unity Catalog CLI.

Permissions required: Recipient object owner.

Catalog Explorer

1. In your Azure Databricks workspace, click Catalog.

2. In the left pane, expand the Delta Sharing menu and select Shared by me.

3. At the top of the Catalog pane, click the gear icon and select Delta Sharing.

   Alternatively, from the Quick access page, click the Delta Sharing > button.

4. On the Shared by me tab, click Recipients, and select the recipient.

5. On the Details tab, under Token Expiration, click Rotate.

6. On the Rotate token dialog, set the token to expire either immediately or for a set period of time. For advice about when to expire existing tokens, see Security considerations for tokens.

7. Click Rotate.

8. On the Details tab, copy the new Activation link and share it with the recipient over a secure channel. See Get the activation link.

CLI

1. Run the following command using the Databricks CLI. Replace the placeholder values:

   • <recipient-name>: the name of the recipient.
   • <expiration-seconds>: The number of seconds until the existing recipient token should expire. During this period, the existing token will continue to work. A value of 0 means the existing token expires immediately. For advice about when to expire existing tokens, see Security considerations for tokens.

   databricks recipients rotate-token \
   <recipient-name> \
   <expiration-seconds>
   

2. Get the recipient’s new activation link and share it with the recipient over a secure channel. See Get the activation link.

Modify the recipient token lifetime

If you need to modify the default recipient token lifetime for your Unity Catalog metastore, you can use Catalog Explorer or the Databricks Unity Catalog CLI.

Permissions required: Account admin.

Catalog Explorer

1. Log in to the account console.
2. In the sidebar, click Catalog.
3. Click the metastore name.
4. Under Delta Sharing recipient token lifetime, click Edit.
5. Enable Set expiration.
6. Enter a number of seconds, minutes, hours, or days, and select the unit of measure.
7. Click Save.

If you disable Set expiration, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

CLI

Run the following command using the Databricks CLI. Replace 12a345b6-7890-1cd2-3456-e789f0a12b34 with the metastore UUID, and replace 86400 with number of seconds before the recipient token expires. If you set this value to 0, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

databricks metastores update \
12a345b6-7890-1cd2-3456-e789f0a12b34 \
--delta-sharing-recipient-token-lifetime-in-seconds 86400