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

现已正式发布：使用代表用户授权构建权限感知的 Databricks 应用 | Databricks 博客

跳至主要内容

Databricks 应用

2026 年 10 月 7 日

现已正式发布：使用代表用户授权构建权限感知的 Databricks 应用

使用 Databricks 应用中的代表用户授权机制，打造个性化、权限感知的数据和 AI 体验实用指南

作者：Aakrati Talati、Cynthya Peranandam、Tushar Madan、Evan Pandya 和 Theo Fernandez

摘要

• 构建权限感知的 Databricks 应用：使用应用授权处理应用自有工作负载，使用代表用户授权处理由登录用户控制的操作。

• 通过作用域限制访问：API 作用域限制应用代表用户能执行的操作；用户的仓库和 Unity Catalog 权限限制其可访问的数据范围。

• 大规模安全运行：保持应用客户端和用户客户端分离，仅将转发的令牌用于当前请求，若令牌缺失则默认拒绝。绝不存储用户令牌。

Databricks 应用使开发者能够直接在 Databricks 平台上构建和部署数据及 AI 应用，从交互式仪表板和运营工具到定制 AI 代理。

现已正式发布，代表用户（OBO）授权机制使开发者能够构建无需在应用代码中重新实现数据治理规则即可提供个性化、权限感知体验的应用。当应用使用 OBO 调用支持的 Databricks API 时，会使用登录用户的身份进行操作：Unity Catalog 会强制执行该用户的现有数据权限（包括行过滤器和列掩码），API 作用域限制应用可代表用户执行的操作。应用仍可使用其专用服务主体处理应用自有操作，例如读取共享配置或写入应用指标。

例如，销售洞察助手可以仅使用销售人员被授权访问的账户和字段来回答问题，而无需赋予应用广泛的 SQL 或工作区管理权限。

从治理每个操作的身份开始

设计应用时，请问：哪个用户的权限应控制此特定操作？

Databricks 应用支持两种互补的授权模型：应用授权和用户授权。应用授权使用应用的专用服务主体，适用于应用自有操作或应向所有用户返回相同结果的体验。用户授权在用户的权限应控制操作时使用登录用户的身份。大多数生产应用都可以使用这两种模型，根据每个请求路径选择合适的身份。参见《在 Databricks 应用中配置授权》。

操作 | 授权身份 | 作用域 | 原因 --- | --- | --- | --- 查询当前用户过滤的数据 | 用户授权（OBO） | API 作用域：sql:restricted-query | 查询以用户身份运行，仅限只读 SQL 查询 读取共享配置或元数据 | 应用授权 | 应用身份权限 | 应用的服务主体提供一致的访问权限 运行后台作业或维护任务 | 背景工作不应依赖用户会话 | 无 | 无 在受控数据上执行用户触发的操作 | 该操作所需 API 作用域 | 使用发起用户权限评估操作 | 无 将共享行为与用户特定数据结合 | 两者 | 为每个用户授权功能分配独立 API 作用域 | 无

使用应用客户端处理应用拥有的操作，使用用户客户端处理受管理的操作。

考虑一个回答以下问题的应用：本季度我的账户表现如何？变化的原因是什么？该应用需要：

• 以请求用户的名义查询销售和客户数据。
• 遵循Unity Catalog权限，包括行级过滤器和列掩码。
• 返回只读分析结果。
• 可选地调用独立服务对结果进行汇总。
• 避免修改数据或管理SQL资源。

这与用户授权机制天然契合。应用将请求用户的转发访问令牌传递给SQL连接器，Databricks会基于该用户的现有仓库和Unity Catalog权限评估查询。区域经理可能仅能看到所在区域的账户，而全国负责人能看到所有区域的数据，无需应用在代码中重新实现这些规则。当管理员更新Unity Catalog策略时，后续的请求会自动反映这些变更。

用户的权限决定了查询能返回哪些数据。下一个设计决策是：应用在用户授权下能代表用户执行哪些操作。

使用与任务最匹配的最小API范围

销售洞察助手需要执行只读查询。它不需要广泛的SQL访问权限来管理资源或执行其他SQL操作。因此，应请求sql:restricted-query而非更广泛的sql范围。

sql:restricted-query允许应用执行只读SQL查询，但禁止执行其他SQL操作。这使应用的行为与授权边界更匹配：应用可以读取受管理数据进行分析，但不能将用户身份作为广泛SQL操作的凭证。

如果应用还需要代表用户调用Genie或Unity Gateway，只需请求对应的权限范围（如genie或ai-gateway）。除非应用确实使用这些功能，否则不要请求文件、模型服务或向量搜索等权限。

权限范围是能力上限而非数据访问授权。应用必须拥有合适的API范围，同时用户仍需具备访问目标资源的权限。详见基于权限范围的安全机制和权限升级。

通过显式API范围配置应用

在Databricks UI或声明式自动化捆绑包中配置用户授权。

对于只读分析助手，应用可以声明：

{
  "userAuthorization": {
    "apiScopes": ["sql:restricted-query"]
  }
}

注意：API范围是应用声明的用户授权配置的一部分。它不会授予SQL仓库或Unity Catalog数据的访问权限。请求用户仍需被允许使用目标SQL仓库，并且需要对查询数据具有必要的Unity Catalog权限。

当用户首次访问用户授权应用时，Databricks会提示用户确认请求的API范围。

将用户身份传递给SQL连接器

Databricks通过x-forwarded-access-token HTTP头转发当前用户的访问令牌。应用应获取该令牌用于需要用户上下文访问的请求，并将其传递给SQL连接器。

以下示例使用Flask和Databricks SQL Connector for Python明确展示令牌传递过程。如果使用Databricks AppKit构建应用，应用相同授权原则：对用户特定操作使用用户上下文客户端或请求时身份，而应用拥有的操作则使用应用身份。

注意：转发的令牌是临时的，仅限于单次请求。应用会在每次请求时读取该令牌，且不会在请求之间或会话中存储该令牌。与应用授权的重要区别在于，连接器通过 access_token 接收转发的用户令牌。sql:restricted-query API 范围将应用限制为所需的只读 SQL 功能，而 Unity Catalog 会确定用户实际可以访问的行和列。请参阅使用用户授权进行查询。

让工作区管理员设置上限边界

开发者指定其应用需要的 API 范围。工作区管理员可以控制允许应用开发者在工作区中添加到应用的 API 范围。

该策略使团队能够构建只读分析和 AI 体验，同时防止应用请求更广泛或无关的功能。应用开发者无法将应用的授权扩展到工作区配置的 API 范围边界之外。

这为组织提供了两个控制层级：

• 应用声明其功能所需的最小 API 范围。
• 工作区管理员定义该工作区中应用可访问的最大 API 范围。

工作区管理员在 设置 > 开发 > 应用 下配置此允许列表。该设置默认包含所有支持的 API，可缩小到选定的 API 范围，或设置为 None 以禁用用户授权。请参阅限制用户授权范围。

即使这些范围未包含在工作区允许列表中，账户管理员仍可添加范围。如果管理员之后移除了允许的范围，已使用该范围运行的应用可以继续运行，但直到移除非允许范围之前，这些应用无法启动、部署或更新。

保持应用所有和用户所有操作的分离

许多有用的应用需要两种授权模型。销售洞察助手可能需要：

• 使用应用范围客户端写入应用指标或读取共享配置。
• 使用带有 sql:restricted-query 的用户范围客户端查询当前用户的数据。
• 如果需要代表用户调用其他 Databricks 服务，则需要单独的用户 API 范围。

建议在应用代码中明确标识该身份边界，而不是创建一个通用客户端并在各处重复使用。分离依赖项、名称和测试有助于防止应用凭证被用于用户特定路径，或用户令牌被保留用于后台工作。

如果请求需要用户授权但缺少转发令牌，应采取封闭式失败处理，而不是静默切换到应用的服务主体。否则，应用可能会返回看似有效但使用不同权限生成的响应。这就是为什么上面示例中的 query_as_user 从 require_user_token 开始，而不是在代码中内联处理缺失的头部。

将相同模式应用于代理

部署在 Databricks Apps 上的自定义代理可以使用相同的模式。在请求时的 invoke 或 stream 处理器内部初始化用户范围的工作区客户端（而非在应用启动时），因为转发的用户令牌仅在活跃的用户请求期间可用。使用应用授权处理共享资源和后台操作。请参阅代理的身份验证。

保障实现安全

• 仅请求必需的最小 API 范围。
• 在代码、测试和依赖项连接中将应用所有和用户授权的客户端保持分离。

• 切勿打印、记录或存储转发的访问令牌。

• 将应用管理权限限制为受信任的开发者，并要求对授权相关更改进行同行评审。

• 对于共享和后台操作，应使用应用授权而非保留用户令牌。

• 使用具有不同 Unity Catalog 访问权限的用户进行测试，并在策略变更后重复这些测试。

入门指南

代表用户进行授权可同时实现个性化与治理。用户的 Unity Catalog 权限决定了应用可访问的数据范围，而最匹配的 API 范围决定了应用可代表用户执行的操作范围。要开始使用，请查阅我们的帮助文档以获取更多资源和最佳实践。

在收件箱中获取最新文章

订阅我们的博客，即可将最新文章发送到您的收件箱。

注册

查看所有博客

slice-start id="_gatsby-scripts-1"

slice-end id="_gatsby-scripts-1"