Authentication for AI agents

AI agents often need to authenticate to other resources to complete tasks. For example, a deployed agent might need to access a Vector Search index to query unstructured data, a serving endpoint to call a foundation model, or Unity Catalog functions to execute custom logic.

This page covers authentication methods for agents deployed on Databricks Apps. For agents deployed on Model Serving endpoints, see Authentication for AI agents (Model Serving).

Databricks Apps provides two authentication methods for agents. Each method serves different use cases:

Method	Description	When to use
App authorization	Agent authenticates using an automatically created service principal with consistent permissions. Previously called Service Principal authentication.	Most common use case. Use when all users should have the same access to resources.
User authorization	Agent authenticates using the identity of the user making the request. Previously called On-Behalf-Of (OBO) authentication.	Use when you need user-specific permissions, audit trails, or fine-grained access control with Unity Catalog.

You can combine both methods in a single agent. For example, use app authorization to access a shared Vector Search index while using user authorization to query user-specific tables.

App authorization

By default, Databricks Apps authenticate using app authorization. Azure Databricks automatically creates a service principal when you create the app, and it acts as the app's identity.

All users who interact with the app share the same permissions defined for the service principal. This model works well when you want all users to see the same data or when the app performs shared operations not tied to user-specific access controls.

For detailed information about app authorization, see App authorization.

Grant permissions to the MLflow experiment

Your agent needs access to an MLflow experiment to log traces and evaluation results.

Grant the service principal Can Edit permission on the MLflow experiment:

1. Click Edit on your app home page.
2. Navigate to the Configure step.
3. In the App resources section, add the MLflow experiment resource.

See Add an MLflow experiment resource to a Databricks app.

Grant permissions to other Databricks resources

If your agent uses other Databricks resources, such as Genie spaces, Vector Search indexes, or SQL warehouses, grant the service principal permissions through the Databricks Apps UI. See Add resources to a Databricks app for the complete list of supported resources and configuration instructions.

To access the prompt registry, grant CREATE FUNCTION, EXECUTE, and MANAGE permissions on the Unity Catalog schema for storing prompts.

The following table lists the minimum permissions required for agents to access common Databricks resources:

Resource type	Permission
SQL Warehouse	Can Use
Model Serving endpoint	Can Query
Unity Catalog Function	CAN Execute
Genie space	Can Run
Vector Search index	Can Select
Unity Catalog Table	SELECT
Unity Catalog Connection	Use Connection
Unity Catalog Volume	Can Read or Can Read and Write
Lakebase	Can Connect and Create

When granting access to Unity Catalog resources, you must also grant permissions to all downstream dependent resources. For example, if you grant access to a Genie space, you must also grant access to its underlying tables, SQL warehouses, and Unity Catalog functions.

The user adding the resource must have the Can Manage permission on both the resource and the app. For the complete list of supported resources and all available permissions, see supported resource types.

For best practices on managing app authorization securely, including credential management and least privilege principles, see App authorization.

User authorization

Important

User authorization is in Public Preview. Your workspace admin must enable it before you can use user authorization.

User authorization allows an agent to act with the identity of the user making the request. This provides:

• Per-user access to sensitive data
• Fine-grained data controls enforced by Unity Catalog
• User-specific audit trails
• Automatic enforcement of row-level filters and column masks

Use user authorization when your agent needs to access resources using the requesting user's identity instead of the app's service principal.

How user authorization works

When you configure user authorization for your agent:

1. Add API scopes to your app: Define which Databricks APIs the app can access on behalf of users. See Add scopes to an app.
2. User credentials are downscoped: Azure Databricks takes the user's credentials and restricts them to only the API scopes you defined.
3. Token forwarding: The downscoped token is made available to your app through the x-forwarded-access-token HTTP header.
4. MLflow AgentServer stores the token: The Agent Server automatically stores this token per request for convenient access in agent code.

Configure user authorization by adding scopes in the Databricks Apps UI when creating or editing your app, or programmatically using the API. See Add scopes to an app for detailed instructions.

Agents with user authorization can access the following Databricks resources:

• SQL Warehouse
• Genie Space
• Files and directories
• Model Serving Endpoint
• Vector Search Index
• Unity Catalog Connections
• Unity Catalog Tables

Implement user authorization

To implement user authorization, you must add authorization scopes to your app. Scopes restrict what the app can do on the user's behalf.

1. In the Databricks UI, go to your Databricks Apps Authorization settings.
2. Click +Add scope and select the scopes that you want to access resources on behalf of the user.
3. Save the changes.

To configure user authorization in your agent code, retrieve the header for this request from the AgentServer and construct a workspace client with those credentials.

1. In your agent code, import the authentication utility:

   If using one of the provided templates from databricks/app-templates, import the provided utility:

   from databricks_app.utils import get_user_workspace_client
   

   Otherwise, import from the Agent Server utilities:

   from agent_server.utils import get_user_workspace_client
   

   The get_user_workspace_client() function uses the Agent Server to capture the x-forwarded-access-token header and constructs a workspace client with those user credentials, handling authentication between the user, app, and agent server.

2. Initialize the workspace client at query time, not during app startup:

   Important

   Call get_user_workspace_client() inside the invoke and stream handlers, not in __init__ or at app startup. User credentials are only available at query time when a user makes a request. Initializing during app startup will fail because no user context exists yet.

   # In your agent code (inside invoke or stream handler)
   user_client = get_user_workspace_client()
   
   
   # Use user_client to access Databricks resources with user permissions
   response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)
   

For a complete guide on adding scopes and understanding scope-based security, see Scope-based security and privilege escalation.

Authenticate to Databricks MCP servers

To authenticate to Databricks MCP servers, specify all the resources your agent needs in your databricks.yaml file. Grant the app's service principal (or users, if using user authorization) access to all downstream resources.

For example, if your agent uses the MCP server URLs listed below, you must grant access to all vector search indexes in the prod.customer_support and prod.billing schemas, and all Unity Catalog functions in prod.billing:

• https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/customer_support
• https://<your-workspace-hostname>/api/2.0/mcp/vector-search/prod/billing
• https://<your-workspace-hostname>/api/2.0/mcp/functions/prod/billing

Configure authentication with Databricks Asset Bundles

You can configure all authentication settings programmatically using Databricks Asset Bundles instead of the Databricks Apps UI. This page shows UI-based configuration to illustrate what resources and permissions are needed, but the same configuration can be defined in your bundle YAML files. See Apps in bundles for the complete bundle configuration reference.

Next steps

• Author an AI agent and deploy it on Databricks Apps
• Configure authorization in a Databricks app
• Add resources to a Databricks app