Now GA: Building permission-aware Databricks Apps with on-behalf-of-user authorization

Databricks Apps lets developers build and deploy data and AI applications directly on the Databricks platform, from interactive dashboards and operational tools to custom AI agents.

Now generally available, on-behalf-of-user (OBO) authorization makes it possible to build apps that deliver personalized, permission-aware experiences without reimplementing data-governance rules in application code. When an app calls supported Databricks APIs with OBO, it acts using the signed-in user’s identity: Unity Catalog enforces that user’s existing data permissions, including row filters and column masks, and API scopes limit the operations the app can perform on the user’s behalf. Apps can continue to use their dedicated service principal for app-owned operations, such as reading shared configuration or writing application metrics.

For example, a sales-insights assistant can answer questions using only the accounts and fields a salesperson is authorized to access, without giving the app broad SQL or workspace-administration capabilities.

When designing an app, ask: Whose permissions should govern this particular operation?

Databricks Apps supports two complementary authorization models: app authorization and user authorization. App authorization uses the app’s dedicated service principal and is appropriate for app-owned operations or experiences that should return the same result to every user. User authorization uses the signed-in user’s identity when that user’s permissions should govern an operation. Most production apps can use both models, choosing the appropriate identity for each request path. See Configure authorization in a Databricks app.

The query runs as the user and is limited to read-only SQL queries.

The query runs as the user and is limited to read-only SQL queries.

The app’s service principal provides consistent access.

The app’s service principal provides consistent access.

Background work should not depend on a user session.

Background work should not depend on a user session.

The action is evaluated using the initiating user’s permissions.

The action is evaluated using the initiating user’s permissions.

Use an app client for app-owned operations and a user client for governed operations.

Use an app client for app-owned operations and a user client for governed operations.

Consider an app that answers questions such as: How are my accounts performing this quarter, and what explains the change? The app needs to:

Query sales and customer data as the requesting user.

Respect Unity Catalog permissions, including row-level filters and column masks.

Return read-only analysis.

Optionally call a separate service to summarize the results.

Avoid modifying data or managing SQL resources.

This is a natural fit for user authorization. The app passes the requesting user’s forwarded access token to the SQL connector, and Databricks evaluates the query using that user’s existing warehouse and Unity Catalog permissions. A regional manager might see only accounts in their region, while a national leader sees all regions, without the app recreating those rules in code. When administrators update Unity Catalog policies, subsequent app requests reflect those changes.

The user’s permission determines which data the query can return. The next design decision is what the app is allowed to do on the user’s behalf with the forwarded user token.

The sales-insights assistant needs to execute read-only queries. It does not need broad SQL access to manage resources or perform other SQL operations. For that reason, it should request sql:restricted-query rather than the broader sql scope.

sql:restricted-query allows the app to execute read-only SQL queries. It does not allow the app to perform other SQL operations. This creates a better match between the app’s product behavior and its authorization boundary: the app can read governed data for analysis, but it cannot use the user’s identity as a broad SQL operating credential.

If the app also invokes Genie or Unity Gateway on a user’s behalf, request only the corresponding scopes, such as genie or ai-gateway. Do not request files, model-serving, or vector-search unless the app actually uses those capabilities.

Scopes are a capability ceiling, not a grant of data access. The app must have the appropriate API scope, and the user must still have permission to access the target resource. See Scope-based security and privilege escalation.

Configure user authorization in the Databricks UI or in a Declarative Automation Bundle.

Note: The API scope is part of the app’s declared user-authorization configuration. It does not grant access to a SQL warehouse or Unity Catalog data. The requesting user must still be allowed to use the target SQL warehouse and have the required Unity Catalog privileges on the data being queried.

When a user first accesses a user-authorized app, Databricks prompts them to consent to the requested API scopes.

Databricks forwards the current user’s access token in the x-forwarded-access-token HTTP header. The app should retrieve that token for the request that needs user-context access and pass it to the SQL connector.

The following example uses Flask and the Databricks SQL Connector for Python to make the token flow explicit. If you build the app with Databricks AppKit, apply the same authorization principle: use the user-context client or request-time identity for user-specific operations, and keep app-owned operations on the app identity.

Note: The forwarded token is short-lived and per-request. The app reads it on each request and never stores it across requests or in a session.

The important difference from app authorization is that the connector receives the forwarded user token through access_token. The sql:restricted-query API scope limits the app to the read-only SQL capability it needs, while Unity Catalog determines which rows and columns that user can actually access. See Query with user authorization.

Developers specify which API scopes their app needs. Workspace administrators can control which API scopes app developers are allowed to add to apps in the workspace.

That policy lets teams build read-only analytics and AI experiences while preventing apps from requesting broader or unrelated capabilities. An app developer cannot expand the app’s authorization beyond the workspace’s configured API-scope boundary.

The app declares the minimum API scopes required for its functionality.

The workspace administrator defines the maximum API scopes available to apps in that workspace.

Workspace administrators configure this allowlist under Settings > Development > Apps. The setting defaults to all supported APIs, can be narrowed to selected API scopes, or can be set to None to disable user authorization. See Restrict user authorization scopes.

Account administrators can add scopes even when those scopes are not included in the workspace allowlist. If an administrator later removes an allowed scope, apps already running with that scope can continue running, but they cannot be started, deployed, or updated until the non-allowed scope is removed.

Many useful apps need both authorization models. The sales insights assistant might use:

An app-scoped client to write application metrics or read shared configuration.

A user-scoped client with sql:restricted-query to query data for the current user.

A separate user API scope if it needs to invoke another Databricks service on the user’s behalf.

It is advisable to make that identity boundary explicit in application code instead of creating one generic client and reusing it everywhere. Separate dependencies, names, and tests help prevent an app credential from being used for a user-specific path or a user token from being retained for background work.

If a request requires user authorization and the forwarded token is missing, fail closed rather than silently switching to the app’s service principal. Otherwise, the app could return a response that looks valid but was generated with different permissions. That is why query_as_user in the example above starts with require_user_token instead of handling the missing header inline.

Custom agents deployed on Databricks Apps can use the same model. Initialize the user-scoped workspace client inside the request-time invoke or stream handler—not at application startup—because the forwarded user token is available only during an active user request. Use app authorization for shared resources and background operations. See Authentication for agents.

Request only the minimum API scopes required.

Keep app-owned and user-authorized clients separate in code, tests, and dependency wiring.

Never print, log, or persist forwarded access tokens.

Restrict app management to trusted developers and require peer review for authorization-related changes.

Use app authorization for shared and background operations rather than retaining user tokens.

Test with users whose Unity Catalog access differs, then repeat those tests after policy changes.

On-behalf-of-user authorization gives you personalization and governance from the same mechanism. The user's Unity Catalog permissions decide what data an app can reach, and the narrowest matching API scope decides what it can do on their behalf. To get started, check out our help documentation for more resources and best practices.