Connect Azure Databricks to a OneLake external location

This page explains how to connect to OneLake using an external location. With the connection, you can create Unity Catalog objects (tables, volumes, views, Materialized views, and Streaming tables) and govern your data through Unity Catalog. If you want to read existing OneLake data from Azure Databricks without writing, see Enable OneLake catalog federation.

To connect to a OneLake path, you must have two Unity Catalog securable objects:

• A storage credential, which specifies a managed identity or service principal that grants access to your OneLake storage.
• An external location, which defines the ID-based ABFSS path to your OneLake storage and references the storage credential.

Requirements

• Databricks Runtime 18.1 or above, or serverless compute
• Active Microsoft Fabric workspace with capacity assigned
• CREATE STORAGE CREDENTIAL privilege on the Unity Catalog metastore, and CREATE EXTERNAL LOCATION privilege on both the metastore and the storage credential
• Your Azure Databricks workspace must be enabled for Unity Catalog
• A Fabric administrator must enable Users can create Azure Databricks Storage items in Administrator Portal > Tenant Settings
• The target Fabric workspace must have Authenticate with OneLake user-delegated SAS tokens enabled in Workspace settings > Delegated settings > OneLake Settings

Security model

Access to the Azure Databricks Storage item in a Fabric workspace is restricted to the assigned managed identity. OneLake security, which is enabled by default, allows explicit permissions at the workspace and item level to grant open, discover, read, and write access to OneLake from Azure Databricks.

Configure Fabric-side item permissions and OneLake Security roles explicitly for the users, groups, and service principals that need access.

Step 1: Configure identity and access in Azure and Fabric

1. In the Azure portal, create or identify an Access Connector for Azure Databricks with a managed identity, or a service principal.
2. In Microsoft Fabric, go to your target workspace.
3. Click the Workspace settings gear button, then click Manage access.
4. Click Add people or groups and search for your managed identity or service principal.
5. For Fabric workspace or item permission, assign the managed identity or service principal a Viewer role.
6. For data access, create a OneLake Security role and grant read and write permissions to the managed identity or service principal.

Step 2: Provision storage in Fabric and get the path

1. In your Fabric workspace, create a Azure Databricks Storage item.

2. Open Manage OneLake security for the Azure Databricks Storage item and create a OneLake Security role.

3. Add the Azure Databricks managed identity or service principal as a member of the role. Grant the minimum required data permission: Read for read-only access, or ReadWrite when Azure Databricks must create or modify data.

4. After the item is created, construct the ID-based ABFSS path:

   abfss://<WorkspaceID>@onelake.dfs.fabric.microsoft.com/<DatabricksStorageID>/Files/
   

   The workspace ID and Azure Databricks Storage item ID are available in the browser URL when the item is open in Fabric.

   Note

   The external location requires the ID-based path format (GUIDs), not display names. Name-based paths are rejected at creation time.

   Save this path. You use it in Step 4.

Step 3: Create a Unity Catalog storage credential

1. Sign in to your Unity Catalog-enabled Azure Databricks workspace.

2. In the sidebar, click Catalog.

3. Click , then click Create a credential.

4. Select a Credential Type of Azure Managed Identity.

5. Enter a Storage credential name and an optional comment.

6. Enter the Access Connector ID (the resource ID of the access connector associated with your managed identity).

   The resource ID is in the format:

   /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>
   

7. (Optional) If you created the access connector using a user-assigned managed identity, enter the Managed Identity ID.

8. Click Create.

Step 4: Create the OneLake external location

1. In the sidebar, click Catalog.

2. Click , then click Create an external location.

3. Enter an External location name.

4. Under Storage type, select OneLake.

5. Under Storage credential, select the credential you created in Step 3.

6. Under URL, enter the ID-based ABFSS path from Step 2. For example:

   abfss://<WorkspaceID>@onelake.dfs.fabric.microsoft.com/<DatabricksStorageID>/Files/
   

7. Click Create.

8. Click Test connection to verify the external location.

   Note

   A skipped file events read warning during the connection test is expected behavior. File event notifications are not yet supported on OneLake paths. The external location is functioning correctly.

Step 5: Create Unity Catalog objects on the OneLake external location

After you create the external location, you can create a catalog that uses it as managed storage. OneLake stores all the managed tables that you create in that catalog.

-- Create a catalog with the OneLake external location as managed storage
CREATE CATALOG my_onelake_catalog
MANAGED LOCATION '<onelake_external_location_path>';

-- Create a managed table
CREATE TABLE my_onelake_catalog.default.my_table (
  id INT,
  name STRING,
  created_at TIMESTAMP
);

-- Insert data
INSERT INTO my_onelake_catalog.default.my_table
VALUES (1, 'example', current_timestamp());

Replace <onelake_external_location_path> with the external location URL or a sub-path within it.

A OneLake external location supports the following Unity Catalog object types: managed tables (Delta and Iceberg), volumes, views, Materialized views, and Streaming tables.

Troubleshoot

Next steps

• Grant other users permission to use the external location. See Manage external locations.
• Define managed storage locations at the catalog or schema level. See Specify a managed storage location in Unity Catalog.
• Read existing OneLake data from Azure Databricks without writing. See Enable OneLake catalog federation.