Skip to main content
Last updated on

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

This page describes how to create OpenSharing 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 Open ID Connect (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, and Databricks generates a token and a credential file that includes the token. Then, choose whether Databricks emails the recipient or you share the credential file manually using an activation link.

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

  3. The recipient downloads the credential file from the activation link or from the email. They use the credential file to authenticate and get read access to the shared data.

The OIDC federation flow is an alternative to the bearer token flow described in this page. But you can't grant the recipient access using an email. For details, see Enable Open ID Connect (OIDC) federation for OpenSharing recipients.

important

All Databricks-to-Open sharing recipient tokens issued before December 8, 2025, with expiration dates after December 8, 2026, or with no expiration date, automatically expire on December 8, 2026. If you currently use recipient tokens with long or unlimited lifetimes, review your integrations and renew tokens as needed to avoid breaking changes after this date.

Create the recipient​

To create a recipient for Databricks-to-Open sharing, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the CREATE RECIPIENT SQL command in a Databricks notebook or the Databricks SQL query editor. To create a recipient with the REST API, including an email recipient, see Create a recipient in the REST API reference.

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

  2. At the top of the Catalog pane, click the Gear icon. gear icon and select OpenSharing.

    Alternatively, in the upper-right corner, click Share > OpenSharing.

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

  4. Choose how your recipient can access their shares:

    • Share using email (Beta): This sends an email to the recipient so they can download the credential file and read the shared data. See email sharing for details and limitations.

      1. Enter the Recipient name and their Email address.
      2. For Configure how this share can be consumed, select Any supported OpenSharing client or Limit to Token recipients. Any supported OpenSharing client allows your recipient to download a credential file and access the share on Databricks.
      3. The token lifetime defaults to the metastore setting. See Modify the recipient token lifetime.
      note

      When sharing using email, granting share access is what sends the invitation. OpenSharing emails the recipient a secure activation link to download the credential file. The credential file can be downloaded only one time by the recipient.

    • Share using sharing identifier: This generates a credential file that you must manually share with your recipient.

      1. Enter the Recipient name.

      2. Select Open.

      3. (Optional) Set the Token lifetime expiration time (in seconds, minutes, hours, or days from recipient creation time). Leave Set expiration selected to set an expiration time. Tokens are valid for a maximum of one year after creation.

        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.

      4. (Optional) Enter a description for your recipient.

  5. Click Create.

  6. If you did not use email sharing, copy the activation link.

    Alternatively, you can get the activation link later. See Send the recipient their connection information.

  7. (Optional) Create custom Recipient properties.

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

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 Restrict OpenSharing recipient access using IP access lists (Databricks-to-Open sharing).

Send the recipient their connection information​

Instruct the recipient to download the credential file and access the shared data.

Recipients can download the credential file only one time. The downloaded credential should be treated as a secret and must not be shared outside of the 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.

Send using email​

Beta

This feature is in Beta. To use it, an account admin on the provider's account must enable OpenSharing by email from the account console Previews page. See Manage account-level previews.

Your recipient can access and download the credential file from the email. See email sharing limitations.

Send using a sharing identifier​

Use a secure channel to share the activation link and a link to instructions for using it.

If you need to access the activation link, you can use Catalog Explorer, the Databricks Unity Catalog CLI, or the DESCRIBE RECIPIENT SQL command in a 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.

  1. In your Databricks workspace, click Data icon. Catalog.

  2. At the top of the Catalog pane, click the Gear icon. gear icon and select OpenSharing.

    Alternatively, in the upper-right corner, click Share > OpenSharing.

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

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

Grant the recipient access to a share​

After 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 a 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 OpenSharing data shares (for providers).

Manage recipient tokens​

If you are sharing data with a recipient using the Databricks-to-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 (the one being 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.

note

After you share the new activation link, the recipient must apply the new credential on their side. If the recipient imported the credential as a provider object in Unity Catalog, they must update the provider object with the Databricks REST API. See Rotate credentials for open recipients.

  1. In your Databricks workspace, click Data icon. Catalog.

  2. At the top of the Catalog pane, click the Gear icon. gear icon and select OpenSharing.

    Alternatively, in the upper-right corner, click Share > OpenSharing.

  3. In the left pane, expand the OpenSharing menu and select Shared by me.

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

  5. In the rightmost column, under Token management, next to 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 Send the recipient their connection information.

Update recipient token lifetime​

To update the lifetime of an existing recipient token, use Catalog Explorer.

Permissions required: Recipient object owner.

  1. In your Databricks workspace, click Data icon. Catalog.

  2. At the top of the Catalog pane, click the Gear icon. gear icon and select OpenSharing.

    Alternatively, in the upper-right corner, click Share > OpenSharing.

  3. In the left pane, expand the OpenSharing menu and select Shared by me.

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

  5. In the rightmost column, under Token management, next to Token expiration, click Update.

  6. On the Edit recipient token lifetime dialog, set the new token lifetime. For advice about when to expire existing tokens, see Security considerations for tokens.

  7. Click Save.

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.

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.

Permissions required: Account admin.

  1. Log in to the account console.
  2. In the sidebar, click Data icon. Catalog.
  3. Click the metastore name.
  4. Under OpenSharing 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. Tokens are valid for a maximum of one year after creation.
  7. Click Save.

Additional resources​

On this page