Skip to main content

Recipients

A recipient is the named object that represents the identity of a user or group of users 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.

Recipient types​

Databricks-to-Databricks (D2D)​

When your customer is on Databricks with Unity Catalog enabled, create a recipient using their sharing identifier:

CREATE RECIPIENT acme_corp
USING ID 'aws:us-west-2:abc123-def456-ghi789';

This provides secure, tokenless access that integrates directly with Unity Catalog governance and auditing.

Open sharing (D2O)​

For customers not on Databricks, create a recipient that will use bearer tokens:

CREATE RECIPIENT external_partner
COMMENT 'Partner XYZ - Data analytics platform';

After creation, retrieve the activation link to share with your recipient:

DESCRIBE RECIPIENT external_partner;

The activation link allows the recipient to download a credential file containing connection details and token. For full syntax, see CREATE RECIPIENT.

Recipient properties​

Add properties when creating a recipient to enable dynamic entitlements:

CREATE RECIPIENT acme_corp
USING ID 'aws:us-west-2:abc123-def456-ghi789'
PROPERTIES (
  'customer_code' = 'ACME-2024',
  'license' = 'enterprise',
  'territory' = 'north_america'
);

Reference these properties in views using current_recipient():

CREATE VIEW catalog.schema.customer_data AS
SELECT * FROM catalog.schema.base_table
WHERE territory = current_recipient('territory');

See Dynamic Views & Data Filtering for more patterns.

Authentication​

Bearer tokens​

For D2O sharing, you can issue bearer tokens to recipients. Configure token lifetimes at the metastore level and rotate tokens regularly.

Best practices:

  • Use short-lived tokens where possible
  • Implement token rotation workflows
  • Use recipient IP access lists for additional control

OIDC federation​

OIDC federation allows recipients to authenticate using their existing identity provider. This is useful for organizations with established identity management systems.

Encourage recipients to automate token refresh for OIDC flows to avoid access interruptions.

IP access lists​

Restrict recipient access to specific IP ranges:

ALTER RECIPIENT external_partner
SET PROPERTY 'ip_access_list' = '10.0.0.0/8,192.168.1.0/24';

See Restrict recipient access for details.

Granting access​

After creating a recipient, grant them access to a share:

GRANT SELECT ON SHARE sales_data TO RECIPIENT acme_corp;

View current grants:

SHOW GRANTS ON SHARE sales_data;

For full syntax, see GRANT ON SHARE.

What's next​