Filter data per end user using OAuth custom identity claims

Databricks now supports adding custom identity claims to OAuth tokens issued for service principals. This enables row-level data isolation for end users in multi-tenant applications without provisioning individual Databricks user accounts for each client.

Use cases

Imagine you build a SaaS application or customer portal serving hundreds of clients, storing all customer records in shared lakehouse tables. Instead of creating a Databricks user per client or managing isolated tables, your backend queries Databricks using a single service principal.

With this capability, you can:

• Pass a customer identifier or end-user identity directly when generating the service principal's OAuth token.
• Restrict rows using dynamic views or ABAC policies evaluated by current_oauth_custom_identity_claim().
• Join identity claims with mapping tables to resolve user-specific access rules.

How to use

The application requests a token and appends the custom_claim parameter using client credentials or token exchange:

curl --request POST \
  --url https://<workspace-url>/oidc/v1/token \
  --user '<client-id>:<client-secret>' \
  --data 'grant_type=client_credentials' \
  --data 'scope=all-apis' \
  --data-urlencode 'custom_claim=acme'

What happens in this code:

1. Calls the Databricks OAuth token endpoint using the service principal credentials.
2. Supplies custom_claim=acme to bind the authenticated end-user identity into the token payload.

In Unity Catalog, create a dynamic view that checks the claim:

CREATE OR REPLACE VIEW meu_catalogo.meu_schema.minha_view_pedidos AS
SELECT order_id, customer_name, product, quantity, order_date
FROM meu_catalogo.meu_schema.pedidos
WHERE customer_name = current_oauth_custom_identity_claim();

What happens in this code:

1. Declares a dynamic view over the underlying table.
2. Evaluates current_oauth_custom_identity_claim() at query time to extract the token claim.
3. If a token lacks a claim, the function returns NULL, safely matching zero rows.

Limitations and requirements

• Requirements: A service principal configured with an OAuth secret or identity federation policy; a SQL warehouse or compute running Databricks Runtime 19.7 or above.
• Supported surfaces: Databricks JDBC Driver connected to a SQL warehouse, SQL Statement Execution API, and Genie Agents API. Workspace UI SQL editor is not supported.
• Claim constraints: Up to 1,000 printable ASCII characters (including spaces, \t, \n, and \r). Non-ASCII characters (e.g., accents, emoji) fail with HTTP 400. Claims are not encrypted inside the JWT payload; never store sensitive secrets in them.