通过

AI 代理身份验证

AI 代理通常需要向其他资源进行身份验证才能完成任务。 例如，部署的代理可能需要访问矢量搜索索引来查询非结构化数据、用于调用基础模型的服务终结点或 Unity 目录函数来执行自定义逻辑。

本页介绍 Databricks Apps 上部署的代理的身份验证方法。 有关在模型服务终结点上部署的代理，请参阅 AI 代理的身份验证（模型服务）。

Databricks Apps 为代理提供了两种身份验证方法。 每个方法提供不同的用例：

方法 Description 何时使用
应用授权 代理使用具有一致权限的自动创建的服务主体进行身份验证。 以前称为服务主体身份验证。 最常见的用例。 当所有用户应具有相同的资源访问权限时使用。
用户授权 代理使用发出请求的用户标识进行身份验证。 以前称为 On-Behalf-Of （OBO）身份验证。 当您需要为用户指定权限、审核追踪或通过 Unity Catalog 实现精细的访问控制时使用。

可以在单个代理中合并这两种方法。 例如，使用应用授权访问共享矢量搜索索引，同时使用用户授权查询用户特定的表。

应用授权

默认情况下，Databricks 应用使用应用授权进行身份验证。 创建应用时，Azure Databricks 会自动创建服务主体，并充当应用的标识。

与应用交互的所有用户共享为服务主体定义的相同权限。 如果希望所有用户看到相同的数据，或者当应用执行不绑定到用户特定访问控制的共享作时，此模型可以正常工作。

有关应用授权的详细信息，请参阅 应用授权。

向 MLflow 试验授予权限

代理需要访问 MLflow 实验，以便记录日志和评估结果。

授予对 MLflow 试验的服务主体 Can Edit 权限：

  1. 单击应用主页上的 “编辑 ”。
  2. 导航到 “配置” 步骤。
  3. 在 “应用资源 ”部分中，添加 MLflow 试验资源。

请参阅 将 MLflow 试验资源添加到 Databricks 应用。

向其他 Databricks 资源授予权限

如果代理使用其他 Databricks 资源（例如 Genie 空格、矢量搜索索引或 SQL 仓库），请通过 Databricks Apps UI 授予服务主体权限。 有关支持的资源和配置说明的完整列表，请参阅 将资源添加到 Databricks 应用 。

若要访问提示注册表，请在 Unity 目录架构上授予CREATE FUNCTIONEXECUTE和MANAGE权限以存储提示。

下表列出了代理访问常见 Databricks 资源所需的最低权限：

资源类型 许可
SQL 仓库 Can Use
模型服务终结点 Can Query
Unity 目录函数 CAN Execute
精灵空间 Can Run
矢量搜索索引 Can Select
Unity Catalog 表 SELECT
Unity 目录连接 Use Connection
Unity 目录卷 Can Read 或 Can Read and Write
Lakebase Can Connect and Create

授予对 Unity 目录资源的访问权限时，还必须向所有下游依赖资源授予权限。 例如，如果授予对 Genie 空间的访问权限，则还必须向其基础表、SQL 仓库和 Unity 目录函数授予访问权限。

添加资源的用户必须具有 Can Manage 对资源和应用的权限。 有关支持的资源和所有可用权限的完整列表，请参阅 支持的资源类型。

有关安全地管理应用授权的最佳做法，包括凭据管理和最低特权原则，请参阅 应用授权。

用户授权

重要

用户授权为公共预览版。 工作区管理员必须先启用它，然后才能使用用户授权。

用户授权允许代理使用发出请求的用户的标识进行作。 这提供：

  • 对敏感数据的按用户访问
  • Unity Catalog 强制执行的细粒度数据控制
  • 用户特定的审计轨迹
  • 自动强制实施行级筛选器和列掩码

当代理需要使用请求的用户标识（而不是应用的服务主体）访问资源时，请使用用户授权。

用户授权的工作原理

为代理配置用户授权时：

  1. 将 API 范围添加到应用：定义应用可以代表用户访问的 Databricks API。 请参阅 向应用添加范围。
  2. 用户凭据范围缩小：Azure Databricks 使用用户的凭据，并将其范围限制在您定义的 API 范围内。
  3. 令牌转发：通过 HTTP 标头将范围缩小的令牌提供给您的应用 x-forwarded-access-token。
  4. MLflow AgentServer 存储令牌：代理服务器会自动为每个请求存储此令牌，以便在代理代码中方便访问。

通过在创建或编辑应用或以编程方式使用 API 时在 Databricks 应用 UI 中添加范围来配置用户授权。 有关详细说明 ，请参阅向应用添加范围 。

具有用户授权的代理可以访问以下 Databricks 资源：

  • SQL 仓库
  • Genie Space
  • 文件和目录
  • 模型服务终结点
  • 矢量搜索索引
  • Unity 目录连接
  • Unity 目录表

实现用户授权

若要实现用户授权，必须将授权范围添加到应用。 授权范围限制应用可以代表用户执行的操作。

  1. 在 Databricks UI 中，转到 Databricks 应用授权设置。
  2. 单击“ +添加范围 ”，选择要代表用户访问资源的作用域。
  3. 保存更改。

若要在代理代码中配置用户授权，请从 AgentServer 检索此请求的标头，并使用这些凭据构造工作区客户端。

  1. 在代理代码中，导入身份验证实用工具：

    如果使用 databricks/app-templates 提供的模板之一，请导入提供的实用工具：

    from databricks_app.utils import get_user_workspace_client

    否则，请从代理服务器实用工具导入：

    from agent_server.utils import get_user_workspace_client

    该 get_user_workspace_client() 函数使用代理服务器捕获 x-forwarded-access-token 标头，并使用这些用户凭据构造工作区客户端，处理用户、应用和代理服务器之间的身份验证。

  2. 在查询时初始化工作区客户端，而不是在应用启动期间：

    重要

    在invoke和stream处理程序内部调用get_user_workspace_client()，而不是在__init__或应用启动时调用。 用户凭据仅在用户发出请求时可用。 在应用启动期间初始化将失败，因为尚不存在用户上下文。

    # 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)

有关添加范围和了解基于作用域的安全性的完整指南，请参阅 基于作用域的安全性和特权提升。

向 Databricks MCP 服务器进行身份验证

若要向 Databricks MCP 服务器进行身份验证，请在文件中指定代理所需的所有 databricks.yaml 资源。 向应用的服务主体（或使用用户授权）授予对所有下游资源的访问权限。

例如，如果您的代理使用下面列出的 MCP 服务器 URL，则必须授予对 prod.customer_support 和 prod.billing 架构中的所有矢量搜索索引，以及 prod.billing 中所有 Unity Catalog 函数的访问权限。

  • 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

使用 Databricks 资产捆绑配置身份验证

可以使用 Databricks 资产捆绑包而不是 Databricks 应用 UI 以编程方式配置所有身份验证设置。 此页显示基于 UI 的配置，以说明需要哪些资源和权限，但可以在捆绑 YAML 文件中定义相同的配置。 有关完整的捆绑配置参考，请参阅 捆绑包中的应用 。

后续步骤

  • Last updated on