Configure authorization in a Databricks app

Databricks Apps supports secure application development on Databricks. As apps access data and services within a workspace, they must use authentication and authorization mechanisms that enforce data access controls and respect user permissions. The Databricks Apps authorization model is based on OAuth 2.0 and combines the permissions assigned to the app with those of the user accessing it.

To support this framework, Databricks Apps uses two complementary identity models:

• App authorization gives the app its own identity with a consistent set of permissions.
• User authorization allows the app to use the identity and permissions of the user interacting with it.

These models give developers fine-grained control over what the app can access and whose permissions it uses. For example, an app might use app authorization to write logs or read shared configuration. It can then leverage user authorization to query data with the user’s permissions, which Unity Catalog enforces through policies such as row-level or column-level filtering.

App authorization

Each Databricks app has a dedicated service principal that acts as its identity when it accesses Databricks resources. This service principal is unique to the app instance and can’t be reused across apps. Databricks uses this identity to evaluate the app’s permissions independently of any user, which ensures that the app can only access resources explicitly granted to it, even outside the context of user interaction.

This separation helps enforce security boundaries, which enables auditing of app activity and supports scenarios like background processing or automated tasks.

The service principal is represented by a unique ID. You can copy it from the app’s Authorization tab:

When you create an app, Databricks automatically creates a dedicated service principal and assigns it to the app. Use the service principal for actions that the app performs on its own, without requiring the context of an individual user. Common use cases include:

• Running background tasks
• Reading or writing shared configuration or metadata
• Logging activity or usage metrics
• Calling external services through secure endpoints

All actions initiated by the app use the service principal’s permissions. You can grant the service principal access to specific resources using standard permission assignments. However, it doesn’t support user-level access control. All users who interact with the app share the same permissions defined for the service principal, which prevents the app from enforcing fine-grained policies based on individual user identity.

The following example shows how an app uses its service principal to query data in Unity Catalog:

In this case, the service principal needs explicit access to both the SQL warehouse and the Unity Catalog table it queries.

This model works well when you want all users of the app to see the same data or when the app performs shared operations not tied to user-specific access controls.

User authorization

Preview

User authorization is in Public Preview.

User authorization, sometimes referred to as on-behalf-of-user authorization, allows a Databricks Apps app to act with the identity of the app user. Databricks forwards the user’s access token to the app, which uses the token to access resources on the user's behalf. Databricks enforces all permissions based on the user’s existing Unity Catalog policies.

To manage the security risks of apps acting on a user's behalf, Databricks uses scopes to limit what actions an app can perform through user authorization.

Apply user authorization when the app needs to respect individual user permissions. Typical use cases include:

• Querying tables or volumes
• Accessing SQL warehouses or compute
• Running jobs or workflows tied to user actions

All actions use the existing Unity Catalog permissions of the user:

User authorization enables fine-grained access control by applying Unity Catalog features like row-level filters and column masks to app activity. This approach keeps access control consistent with workspace governance and avoids hardcoding permission logic into the app.

Choose an authorization model

Databricks Apps can use app and user authorization independently or together. These models serve different purposes and are designed to work in parallel.

Use app authorization when the app performs operations that don’t depend on the user’s identity. This includes writing logs, accessing shared configuration, or calling external services.

Use user authorization when the app needs to access resources in the context of the user, such as querying data governed by Unity Catalog or launching compute on the user’s behalf.

Many apps combine both models. For example, an app might use its service principal to write usage metrics to a logging table, while leveraging user authorization to run SQL queries that return user-specific results based on row-level access controls.

Implement authorization in apps

To use app or user authorization in Databricks Apps, configure the appropriate identity and pass the correct credentials when you make requests to Databricks services.

Retrieve app authorization credentials

For app authorization, Databricks automatically injects service principal credentials into the app’s environment. The following environment variables hold the required OAuth client values:

Variable	Description
DATABRICKS_CLIENT_ID	Service principal OAuth client ID
DATABRICKS_CLIENT_SECRET	Service principal OAuth client secret

Databricks sets the environment variables automatically in the app runtime. The app uses these variables when it authenticates as itself.

Python

import os

client_id = os.getenv('DATABRICKS_CLIENT_ID')
client_secret = os.getenv('DATABRICKS_CLIENT_SECRET')

Example: Query with app authorization

This example uses the SDK Config object, which pulls service principal credentials from environment variables and performs OAuth authorization.

Python

from databricks import sql
from databricks.sdk.core import Config

cfg = Config()

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    credentials_provider=lambda: cfg.authenticate,
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

Retrieve user authorization credentials

For user authorization, Databricks forwards the user’s identity and access token to the app in HTTP headers. The app must extract these headers to act on the user’s behalf.

How you retrieve these headers depends on the framework you use.

Streamlit

Python

import streamlit as st
user_access_token = st.context.headers.get('X-Forwarded-Access-Token')

Gradio

Python

from fastapi import Request
import gradio as gr

request: Request = gr.Request().get("request")
user_access_token = dict(request.headers).get('X-Forwarded-Access-Token')

Dash and Flask

Python

from flask import request

headers = request.headers
user_token = headers.get('X-Forwarded-Access-Token')

Shiny

Python

user_token = session.http_conn.headers.get('X-Forwarded-Access-Token', None)

Example: Query with user authorization

In this case, the app passes the user’s access token directly to the connector, and Databricks applies the user’s permissions to the query.

Python

from databricks import sql
from databricks.sdk.core import Config
from flask import request

cfg = Config()
user_token = request.headers.get("X-Forwarded-Access-Token")

conn = sql.connect(
    server_hostname=cfg.host,
    http_path="<your-warehouse-http-path>",
    access_token=user_token
)

query = "SELECT * FROM main.sandbox.sales_customers LIMIT 1000"

with conn.cursor() as cursor:
    cursor.execute(query)
    df = cursor.fetchall_arrow().to_pandas()
    print(df.head())

conn.close()

Fine-grained permissions with user authorization

When you add user authorization to an app, it enforces the user's existing Unity Catalog permissions, including:

• Row-level filters to restrict visible rows
• Column masks to redact or transform sensitive data

Because Databricks evaluates user authorization requests with the user’s identity, these policies apply automatically when the app accesses data. For example, if a table includes a row filter that limits visibility by region, the app only returns the rows that the user is allowed to query. No additional filtering logic is needed in the app.

This approach avoids duplicating access control logic in application code and ensures consistency with workspace-level governance. When admins update Unity Catalog policies, the app automatically respects those changes. This reduces the risk of data exposure from stale or misaligned permission logic.

Scope-based security and privilege escalation

Apps that use user authorization must declare specific authorization scopes to control what the app can do on the user’s behalf. Scopes restrict access to specific APIs or resource types, such as:

• sql for querying SQL warehouses
• serving.serving-endpoints for model serving
• vectorsearch.vector-search-endpoints for vector search

If you don’t select any scopes, Databricks assigns a default set that allows the app to retrieve basic user identity information:

• iam.access-control:read
• iam.current-user:read

These defaults are required to support user authorization functionality, but they don’t permit access to data or compute resources. You can add additional scopes when you create or edit the app.

Scopes enforce the principle of least privilege. Make sure to configure the app to request only the scopes that it needs. Databricks blocks access to any functionality outside the approved scopes, even if the user has permission. For example, if the app requests only the sql scope, it can’t access model serving endpoints, even if the user could outside the app.

When a user first accesses an app, Databricks prompts them to explicitly authorize the app to act within the requested scopes. Admins can optionally grant consent on behalf of users to align access with organizational policies.

Configure user authorization in your app

Preview

User authorization is in Public Preview. Your workspace admin must enable it before you can add scopes to your app.

You can configure user authorization when you create or edit an app in the Databricks UI.

In the Configure step, click +Add scope and select the scopes that define which Databricks APIs or resources the app can access on behalf of the user. Databricks enforces these scopes at runtime and requires user or admin consent before granting access.

For a complete example, see the Databricks Apps authorization demo on GitHub. The example app shows how to use both app and user authorization models, and includes setup instructions and example queries with user authorization.