Databricks auth: Entra ID workload identity¶

Azure Databricks, and only when the collector runs on Azure AKS.

When to use it¶

• The collector runs on an AKS cluster with workload identity enabled.
• You want no secret stored or rotated anywhere.

The pod exchanges a short-lived, automatically rotated token for an Entra ID access token, so there is nothing to expire in your configuration.

Otherwise use:

• Entra ID service principal — same identity model, but with a stored secret. Works anywhere, not just AKS.
• Service principal (OAuth M2M) — on other clouds.

What you need¶

• The collector deployed on AKS with workload identity available.
• Permission to create an app registration (or a user-assigned managed identity) in Entra ID.
• Workspace admin rights, to add a service principal.

Step 1 — Set up workload identity on the cluster¶

This is done in the Trust3 portal:

1. Open the runtime configuration page.
2. Go to Cloud Permissions → Setup Guide.
3. Follow the steps for your cluster.

That guide covers:

• Enabling workload identity and the OIDC issuer on the AKS cluster.
• Annotating the collector's Kubernetes ServiceAccount with azure.workload.identity/client-id.
• Creating the federated identity credential whose subject is system:serviceaccount:<namespace>:<service-account-name>.

Step 2 — Add the application to Databricks¶

In the steps below, choose Microsoft Entra ID managed at step 3 and paste the application (client) ID from step 1.

In the Databricks workspace:

1. Click your user profile (top right) → Settings.
2. Go to Identity and access → Service principals → Add service principal.
3. Pick how the service principal is managed:
   • Databricks managed — for Service principal (OAuth M2M).
   • Microsoft Entra ID managed — for either Entra ID method. Paste the Entra application (client) ID into the Microsoft Entra application ID field.
4. Enter a Service principal name.
   • Free text, and only a display label in Databricks.
   • Use anything recognizable, for example trust3-collector.

5. Tick these workspace entitlements:

   Entitlement	Why it is needed
   Workspace access	Lets the service principal authenticate to the workspace.
   Databricks SQL access	Needed to query the system catalog through a SQL warehouse for model usage traces.
   Admin access	Covers all current and future workspace objects, so new clusters, jobs, serving endpoints and apps are discovered without a fresh grant each time. Also enables user email resolution on traces and ACL enrichment on assets.

6. Click Add service principal.

This registers the service principal in the account and assigns it to this workspace in one step.

Step 3 — Fill in the collector form¶

In the collector's Datasource Configuration:

That is the whole configuration. Choosing this method shows no credential fields — the identity and its short-lived token come from the cluster setup in step 1.

Step 4 — Grant permissions¶

Grants are keyed on the application (client) ID:

• The asset permissions in Assets permissions.
• The system catalog grants below, if model usage collection is enabled.

Workspace entitlements are not Unity Catalog privileges. Even with Admin access, the identity needs these grants or the model usage and serving endpoint usage collectors return no rows.

• Run them as a metastore admin or account admin.
• Replace the principal with the identity the collector authenticates as.

1
2
3
4
5
6
7
8
9

-- Catalog / schema access
GRANT USE CATALOG ON CATALOG system TO `<collector-principal>`;
GRANT USE SCHEMA ON SCHEMA system.ai_gateway TO `<collector-principal>`;
GRANT USE SCHEMA ON SCHEMA system.serving TO `<collector-principal>`;

-- Table SELECT (model usage collectors)
GRANT SELECT ON TABLE system.ai_gateway.usage TO `<collector-principal>`;
GRANT SELECT ON TABLE system.serving.endpoint_usage TO `<collector-principal>`;
GRANT SELECT ON TABLE system.serving.served_entities TO `<collector-principal>`;

You also need a SQL warehouse for these queries:

• Grant Can Use on it: SQL Warehouses → your warehouse → Permissions.
• Copy its HTTP path from Connection details and enter it in the collector's SQL warehouse HTTP path field.

Read more¶

• Use Microsoft Entra Workload ID with AKS