Create and manage data recipients for Delta Sharing

This article explains how to create and manage recipients for Delta Sharing.

A recipient is the named object that represents the identity of a user or group of users in the real world who consume shared data. The way you create recipients differs depending on whether or not your recipient has access to a Databricks workspace that is enabled for Unity Catalog:

  • For recipients with access to a Databricks workspace that is enabled for Unity Catalog, you can create a recipient object with a secure connection managed entirely by Databricks. This sharing mode is called Databricks-to-Databricks sharing.

  • For recipients without access to a Databricks workspace that is enabled for Unity Catalog, you must use open sharing, with a secure connection that you manage using token-based authentication.

For more information about these two sharing modes and when to choose which, see Open sharing versus Databricks-to-Databricks sharing.

Requirements

To create a recipient:

  • You must be a metastore admin or have the CREATE_RECIPIENT privilege for the Unity Catalog metastore where the data you want to share is registered.

  • You must create the recipient using a Databricks workspace that has that Unity Catalog metastore attached.

  • If you use a notebook or Databricks SQL query to create the recipient, the cluster or SQL warehouse that you use must meet the following requirements:

    • If you use a Databricks notebook to create the recipient, your cluster must use Databricks Runtime 11.2 or above and a Unity-Catalog-capable cluster access mode.

    • If you use Databricks SQL, your SQL warehouse must use compute version 2022.35 and above.

For other recipient management operations (such as view, delete, and update) see the permissions requirements listed in the operation-specific section.

Create a recipient object for users who have access to Databricks (Databricks-to-Databricks sharing)

If your data recipient has access to a Databricks workspace that has been enabled for Unity Catalog, you can create a recipient object with an authentication type of DATABRICKS.

A recipient object with the authentication type of DATABRICKS represents a data recipient on a particular Unity Catalog metastore, identified in the recipient object definition by a sharing identifier string consisting of the metastore’s cloud, region, and UUID. The data shared with this recipient can be accessed only on that metastore.

Step 1: Request the recipient’s sharing identifier

Ask a recipient user to send you the sharing identifier for the Unity Catalog metastore that is attached to the workspaces where the recipient user or group of users will work with the shared data.

The sharing identifier is a string consisting of the metastore’s cloud, region, and UUID (the unique identifier for the metastore), in the format <cloud>:<region>:<uuid>.

For example, in the following screenshot, the complete sharing identifier string is aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

example of CURRENT_METASTORE

The recipient can find the identifier using Data Explorer, the Databricks Unity Catalog CLI, or the default SQL function CURRENT_METASTORE in a Databricks notebook or Databricks SQL query that runs on a Unity-Catalog-capable cluster in the workspace they intend to use.

To get the sharing identifier using Data Explorer:

  1. In your Databricks workspace, click Data Icon Data.

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

  3. Above the Providers tab, click the Sharing identifier copy icon.

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

SELECT CURRENT_METASTORE();

Run the following command using the Databricks CLI. The sharing identifier is returned as the global_metastore_id.

databricks unity-catalog metastores get-summary

You can help the recipient by sending your contact the information contained in this step, or you can point them to Get access in the Databricks-to-Databricks model.

Step 2: Create the recipient

To create a recipient for Databricks-to-Databricks sharing, you can use Data Explorer, the Databricks Unity Catalog CLI, or the CREATE RECIPIENT SQL command in a 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.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. Click New Recipient.

  4. Enter the recipient Name and Sharing identifier.

    Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:us-west-2:19a84bee-54bc-43a2-87de-023d0ec16016.

  5. (Optional) Enter a comment.

  6. Click Create.

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

CREATE RECIPIENT [IF NOT EXISTS] <recipient_name>
USING ID '<sharing_identifier>'
[COMMENT "<comment>"];

Use the entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

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

  • <recipient_name>: The name of the recipient.

  • <sharing_identifier>: The entire sharing identifier string in the format <cloud>:<region>:<uuid>. For example, aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef.

databricks unity-catalog recipients create --name <recipient_name> --sharing-id <sharing_identifier>

The recipient is created with the authentication_type of DATABRICKS.

Create a recipient object for all other users (open sharing)

If you want to share data with users outside of your Databricks workspace, regardless of whether they use Databricks themselves, you can use open Delta Sharing to share your data securely. 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, 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.

  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 you give them access to.

Step 1: Create the recipient

To create a recipient for open sharing, you can use Data Explorer, the Databricks Unity Catalog CLI, or the CREATE RECIPIENT SQL command in a 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.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. Click New Recipient.

  4. Enter the recipient Name

  5. (Optional) Enter a comment.

  6. Click Create.

You do not use the sharing identifier for open sharing recipients.

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

CREATE RECIPIENT [IF NOT EXISTS] <recipient_name>
[COMMENT "<comment>"];

Run the following command using the Databricks CLI.

databricks unity-catalog recipients create --name <recipient_name>

Output includes the activation_url that you share with the recipient.

The recipient is created with the authentication_type of TOKEN.

Note

When you create the recipient, you have the option to limit recipient access to a restricted set of IP addresses. You can also add an IP access list to an existing recipient. See Use IP access lists to restrict Delta Sharing recipient access (open sharing).

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 Data Explorer, the Databricks Unity Catalog CLI, or the GRANT ON SHARE SQL command in a Databricks notebook or the Databricks SQL query editor.

For instructions, see Grant and manage access to Delta Sharing data shares.

Send the recipient their connection information

You must let the recipient know how to access the data that you are sharing with them. The information that you share with the recipient depends on whether you are using Databricks-to-Databricks sharing or open sharing:

  • For Databricks-to-Databricks sharing, you send a link to instructions for accessing the data you are sharing.

    A provider object that lists available shares is automatically created in the recipient’s metastore. Recipients don’t need to do anything but view and select the shares they want to use. See Read data shared using Databricks-to-Databricks Delta Sharing.

  • For open sharing, you 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.

View recipients

To view a list of recipients, you can use Data Explorer, the Databricks Unity Catalog CLI, or the SHOW RECIPIENTS SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: The list of recipients returned depends on your role and permissions. Metastore admin see all recipients. Otherwise, you can view only the recipients for which you are the recipient object owner.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. Open the Recipients tab.

Run the following command in a notebook or the Databricks SQL query editor. Optionally, replace <pattern> with a `LIKE` predicate.

SHOW RECIPIENTS [LIKE <pattern>];

Run the following command using the Databricks CLI.

databricks unity-catalog recipients list

View recipient details

To view details about a recipient, you can use Data Explorer, the Databricks Unity Catalog CLI, or the DESCRIBE RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or the recipient object owner.

Details include:

  • The recipient’s creator, creation timestamp, comments, and authentication type (TOKEN or DATABRICKS).

  • If the recipient uses open sharing: the token lifetime, activation link, activation status (whether the credential has been downloaded), and IP access lists, if assigned.

  • If the recipient uses Databricks-to-Databricks sharing: the cloud, region, and metastore ID of the recipient’s Unity Catalog metastore, as well as activation status.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. On the Recipients tab, find and select the recipient.

  4. View recipient details on the Details tab.

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

DESCRIBE RECIPIENT <recipient_name>;

Run the following command using the Databricks CLI.

databricks unity-catalog recipients get --name <recipient_name>

View a recipient’s share permissions

To view the list of shares that a recipient has been granted access to, you can use Data Explorer, the Databricks Unity Catalog CLI, or the SHOW GRANTS TO RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Permissions required: Metastore admin or the recipient object owner.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. On the Recipients tab, find and select the recipient.

  4. Go to the Shares tab to view the list of shares shared with the recipient.

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

SHOW GRANTS TO RECIPIENT <recipient_name>;

Run the following command using the Databricks CLI.

databricks unity-catalog recipients list-permissions --name <recipient_name>

Update a recipient

To update a recipient, you can use Data Explorer, the Databricks Unity Catalog CLI, or the ALTER RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor.

Properties you can update include recipient name, owner, and comment. You cannot update the recipient name using Data Explorer.

Permissions required: You must be a metastore admin or owner of the recipient object to update the owner. You must be a metastore admin (or user with the CREATE_RECIPIENT privilege) and the owner to update the name. You must be the owner to update the comment.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. On the Recipients tab, find and select the recipient.

  4. On the details page, update the owner or edit the comment.

Run one or more of the following commands in a notebook or the Databricks SQL query editor.

ALTER RECIPIENT <recipient_name> RENAME TO <new_recipient_name>;

ALTER RECIPIENT <recipient_name> OWNER TO <new_owner>;

COMMENT ON RECIPIENT <recipient_name> IS "<new_comment>";

Create a JSON file that includes an update to the recipient name, comment, owner, or IP access list.

{
    "name": "new-recipient-name"
    "owner": "someone-else@example.com"
    "comment": "something new"
    "ip_access_list": {
            "allowed_ip_addresses": ["8.8.8.8", "8.8.8.4/10"]
    }

}

Then run the following command using the Databricks CLI. Replace <recipient_name> with the current recipient name and replace update-recipient-settings.json with the filename of the JSON file.

databricks unity-catalog recipients update --name <recipient_name> --json-file update-recipient-settings.json

Manage recipient tokens (open sharing)

If you are sharing data with a recipient using open sharing, you may need to rotate that recipient’s token.

You should rotate a recipient’s credential and generate a new activation link 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. 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 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 recipient token is compromised, Databricks recommends that you force the existing recipient token to expire immediately.

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

If all recipient tokens have expired, rotating the recipient 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 link 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 link 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 Data Explorer or the Databricks Unity Catalog CLI.

Permissions required: Recipient object owner.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. On the Recipients tab, find and select the recipient.

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

  5. 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.

  6. Click Rotate.

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

  1. Run the following command using the Unity Catalog CLI. Arguments in brackets are optional. Replace the placeholder values:

    • <recipient_name>: the name of the recipient.

    • <expiration_seconds>: Optional. 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 unity-catalog rotate-recipient-token \
      --name <recipient_name> \
      [--existing-token-expire-in-seconds <expiration_seconds>]
    
  2. Get the recipient’s new activation link and share it with the recipient over a secure channel. See Step 2: 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 Data Explorer or the Databricks Unity Catalog CLI.

Note

The recipient token lifetime for existing recipients is not updated automatically when you change the default recipient token lifetime for a metastore. In order to apply the new token lifetime to a given recipient, you must rotate their token. See Manage recipient tokens (open sharing).

Permissions required: Metastore admin.

  1. Log in to the account console.

  2. In the sidebar, click Data Icon Data.

  3. Click the metastore name.

  4. Enable Set expiration.

  5. Enter a number of seconds, minutes, hours, or days, and select the unit of measure.

  6. Click Enable.

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

Create a JSON file that includes an update to the metastore’s delta_sharing_recipient_token_lifetime_in_seconds value. If you set this value to 0, recipient tokens do not expire. Databricks recommends that you configure tokens to expire.

{
  "delta_sharing_recipient_token_lifetime_in_seconds": 86400,
}

Then run the following command using the Databricks CLI. Replace 12a345b6-7890-1cd2-3456-e789f0a12b34 with the metastore UUID, and replace update-metastore.json with the filename of the JSON file.

databricks unity-catalog metastores update --id 12a345b6-7890-1cd2-3456-e789f0a12b34 \
  --json-file update-metastore.json

(Optional) Restrict recipient access using access lists

You can limit recipient access to a restricted set of IP addresses when you configure the recipient object. See Use IP access lists to restrict Delta Sharing recipient access (open sharing).

Delete a recipient

To delete a recipient, you can use Data Explorer, the Databricks Unity Catalog CLI, or the DROP RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor. You must be the recipient object owner to delete the recipient.

When you delete a recipient, the users represented by the recipient can no longer access the shared data. Tokens that recipients use in an open sharing scenario are invalidated.

Permissions required: Recipient object owner.

  1. In your Databricks workspace, click Data Icon Data.

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

  3. On the Recipients tab, find and select the recipient.

  4. Click the Kebab menu kebab menu (also known as the three-dot menu) and select Delete.

  5. On the confirmation dialog, click Delete.

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

DROP RECIPIENT [IF EXISTS] <recipient_name>;

Run the following command using the Databricks CLI.

databricks unity-catalog recipients delete --name <recipient_name>