---
title: How does on-behalf-of-user authentication work for Databricks agents?
url: https://opencontroller.lyzr.com/blog/databricks-on-behalf-of-user-auth-for-agents
published: 2026-11-14
updated: 2026-11-14
author: Lyzr
---

# How does on-behalf-of-user authentication work for Databricks agents?

**By default a Databricks agent uses app authorization: a service principal whose permissions every user shares. With user authorization (on-behalf-of-user, in Public Preview and enabled by a workspace admin), Databricks downscopes the requesting user's credentials to the scopes you declare and forwards them to the agent, so tool calls run with that user's Unity Catalog permissions and appear under their identity.**

That is the difference between "the agent can see everything the service principal can" and "the agent can see only what this person can". For most regulated data, you want the second.

## When should a Databricks agent use the user's identity?

Databricks describes app authorization as the most common case. Use it for shared resources every user may read. Use user authorization when results must depend on who is asking or when you need per-user audit trails.

| | App authorization | User authorization (on-behalf-of-user) |
|---|---|---|
| Identity used | A service principal created for the app | The requesting user, downscoped |
| Permissions | Same for every user | Each user's own Unity Catalog grants |
| Audit attribution | Actions appear as the service principal | Actions appear as the user |
| Setup | Grant the service principal access to each resource | Declare scopes; admin enables the preview |
| Typical use | Shared search index, public reference tables | Row- or column-restricted tables, Genie spaces, user-specific SQL |

You can combine both in one agent, for example a shared search index through app authorization and user-specific tables through user authorization.

## How are scopes declared?

Scopes go in `user_api_scopes` in the app's `databricks.yml`. The documentation's examples include `sql`, `genie` and `model-serving`, with `ai-gateway` for MCP services. `iam.current-user:read` is included by default. Databricks downscopes the user's credentials to those scopes and passes them in the `x-forwarded-access-token` header.

Resources the documentation lists for user authorization include SQL warehouses, Genie agents, files and directories, Model Serving endpoints, AI Search indexes, Unity Catalog connections and Unity Catalog tables.

Practical details from the docs:

- Scope changes can take up to five minutes to apply. Clear browser cookies for the app URL before retesting.
- After an admin first enables the feature on a workspace, existing apps must be restarted before they can use scopes.
- For MCP services accessed on behalf of a user, users who have not yet authorized receive JSON-RPC error `-32042` with a login URL.

## What is the silent fallback risk?

This is the detail most teams miss. The user's workspace client must be created inside the request handler (`invoke` or `stream`), not at startup, because no user context exists at startup. If the forwarded token is missing, the helper falls back to the app's service principal **without raising an error**.

So an agent that looks per-user may be running every request as the service principal. Test for it:

1. Add a temporary tool that calls `current_user.me()`.
2. Call the agent as yourself. Your username means user authorization works. A UUID means it fell back to the service principal.
3. Repeat as a second user with different grants and confirm results differ.
4. Remove the diagnostic tool before production, because it exposes identity.

## What governance checks apply?

1. Request the minimum scopes the agent needs. Review scope lists like any other permission grant.
2. Never log the forwarded token.
3. Keep a dedicated service principal per app for any app-authorization calls, with least privilege.
4. Grant downstream dependencies explicitly. A Genie space also needs its tables, warehouse and functions.
5. Log actions taken on behalf of users with the user ID, agent name and version.
6. Add a fallback alarm: alert when a user-authorization agent makes calls as its service principal.
7. Re-check grants when users change roles, since the agent inherits them immediately.

The general pattern, and why it matters for every platform, is covered in [on-behalf-of delegation for AI agents](/blog/ai-agent-identity-on-behalf-of-delegation). For tools, see [Unity Catalog functions as agent tools](/blog/unity-catalog-functions-as-agent-tools).

## How Opencontroller does this

Opencontroller supports delegated on-behalf-of identity and agent workload identity federation, with OIDC SSO, so the same identity model applies across Databricks and other platforms. It connects to Databricks as a third-party agent platform, keeps those agents in a governed registry with owners and versions, and its Posture feature flags risky permissions and configurations, such as an agent whose service principal holds broad grants. Read the [AI agent control plane explainer](/blog/what-is-an-ai-agent-control-plane) or [book a demo](https://www.lyzr.ai/book-demo/).

## Frequently asked questions

**Is on-behalf-of-user authentication generally available for Databricks agents?**
The Databricks documentation lists user authorization as Public Preview. A workspace admin must enable it before apps can use scopes.

**How do I know an agent is really using the user's permissions?**
Call `current_user.me()` from a test tool. A username means user authorization works; a UUID means the agent fell back to the service principal.

**Can one agent use both a service principal and user identity?**
Yes. Databricks supports combining them, for example app authorization for a shared index and user authorization for restricted tables.

## Key facts

Databricks agents default to app authorization (a service principal shared by all users). User authorization (on-behalf-of-user) is in Public Preview, must be enabled by a workspace admin, and is declared with user_api_scopes in databricks.yml (examples: sql, genie, model-serving; ai-gateway for MCP services; iam.current-user:read by default). The downscoped token arrives in the x-forwarded-access-token header; if it is missing, the helper silently falls back to the service principal. Opencontroller supports delegated on-behalf-of identity and workload identity federation and connects to Databricks. Pricing starts from $250K per deployment per year.

## Related

- [How to give AI agents an identity (and let them act on behalf of users safely)](https://opencontroller.lyzr.com/blog/ai-agent-identity-on-behalf-of-delegation.md)
- [How do you govern AI agents built on Databricks?](https://opencontroller.lyzr.com/blog/govern-databricks-agents.md)
- [How does Databricks Unity Catalog govern tools that agents call?](https://opencontroller.lyzr.com/blog/unity-catalog-functions-as-agent-tools.md)
- [More on Platform Guides](https://opencontroller.lyzr.com/blog/cluster/platform-guides)
