Workspace-catalog binding

In Unity Catalog, all catalogs are accessible by default from any workspace attached to the same metastore. Workspace-catalog binding lets you override this default to restrict a catalog to one or more specific workspaces. Access from an unbound workspace is denied, even for users with explicit privilege grants on the catalog.

Why use workspace-catalog binding

Organizational and compliance requirements often specify that certain data must remain accessible only in designated environments. You may also need to:

• Isolate production data from development or test environments.
• Prevent certain data domains from being joined together.
• Ensure that sensitive data can only be processed in specific workspaces.

In Azure Databricks, the workspace is the primary data processing environment, and the catalog is the primary data domain. Workspace-catalog binding connects these two concepts, letting catalog owners and users with the MANAGE privilege define which workspaces can access which catalogs.

How workspace-catalog binding works

When you bind a catalog to specific workspaces, only the workspaces you assign can access the catalog. Any workspace not in the assigned list receives an error when users try to access the catalog, overriding any individual privilege grants those users hold.

In this diagram, prod_catalog is bound to two production workspaces. Even if a user holds a SELECT grant on a table in prod_catalog, they cannot access that table from the Dev workspace.

Read-only access

When binding a catalog to a workspace, you can optionally restrict that workspace to read-only access. All write operations from that workspace to the catalog are blocked.

Default workspace catalog behavior

The exception to the default open behavior is the default workspace catalog created automatically for all new workspaces. This workspace catalog is bound only to its own workspace by default. If you unbind this catalog or extend access to other workspaces, you must grant any required permissions manually, because the workspace admins group is workspace-local and cannot be used across workspaces.

Platform-wide enforcement

Workspace-catalog bindings are enforced consistently across the platform:

• Information schema queries return only the catalogs accessible in the current workspace.
• Data lineage and Catalog Explorer show only catalogs that are assigned to the current workspace.

What can be bound to workspaces

Workspace binding applies beyond catalogs. You can also bind:

• External locations: restrict which workspaces can access specific cloud storage paths. See (Optional) Assign an external location to specific workspaces.
• Storage credentials: restrict which workspaces can use specific cloud credentials. See (Optional) Assign a storage credential to specific workspaces.

• Service credentials: restrict which workspaces can use specific cloud service credentials. See (Optional) Assign a service credential to specific workspaces.

Bind a catalog to one or more workspaces

To assign a catalog to specific workspaces, you can use Catalog Explorer or the Databricks CLI.

Permissions required: Metastore admin, catalog owner, or MANAGE and USE CATALOG on the catalog.

Catalog Explorer

1. Log in to a workspace that is linked to the metastore.

2. Click Catalog.

3. In the Catalog pane, on the left, click the catalog name.

   The main Catalog Explorer pane defaults to the Catalogs list. You can also select the catalog there.

4. On the Workspaces tab, clear the All workspaces have access checkbox.

   If your catalog is already bound to one or more workspaces, this checkbox is already cleared.

5. Click Assign to workspaces and enter or find the workspaces you want to assign.

6. (Optional) Limit workspace access to read-only.

   On the Manage Access Level menu, select Change access to read-only.

   You can reverse this selection at any time by editing the catalog and selecting Change access to read & write.

To revoke access, go to the Workspaces tab, select the workspace, and click Revoke.

CLI

There are two Databricks CLI command groups and two steps required to assign a catalog to a workspace.

In the following examples, replace <profile-name> with the name of your Azure Databricks authentication configuration profile. It should include the value of a personal access token, in addition to the workspace instance name and workspace ID of the workspace where you generated the personal access token. See Personal access token authentication (legacy).

1. Use the catalogs command group's update command to set the catalog's isolation mode to ISOLATED:

   databricks catalogs update <my-catalog> \
   --isolation-mode ISOLATED \
   --profile <profile-name>
   

   The default isolation-mode is OPEN to all workspaces attached to the metastore.

2. Use the workspace-bindings command group's update-bindings command to assign the workspaces to the catalog:

   databricks workspace-bindings update-bindings catalog <my-catalog> \
   --json '{
     "add": [{"workspace_id": <workspace-id>, "binding_type": <binding-type>}...],
     "remove": [{"workspace_id": <workspace-id>, "binding_type": "<binding-type>}...]
   }' --profile <profile-name>
   

   Use the "add" and "remove" properties to add or remove workspace bindings. The <binding-type> can be either "BINDING_TYPE_READ_WRITE" (default) or "BINDING_TYPE_READ_ONLY".

To list all workspace assignments for a catalog, use the workspace-bindings command group's get-bindings command:

databricks workspace-bindings get-bindings catalog <my-catalog> \
--profile <profile-name>

Unbind a catalog from a workspace

Instructions for revoking workspace access to a catalog using Catalog Explorer or the workspace-bindings CLI command group are included in Bind a catalog to one or more workspaces.