Databricks Apps 全面可用：支持用户身份按需授权

Databricks Apps 让开发者可以直接在 Databricks 平台上构建和部署数据与 AI 应用，从交互式仪表板和运维工具到自定义 AI 代理。

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

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

从管辖每个操作的身份开始

在设计应用时，要问：这个特定操作应由谁的权限来管辖？

Databricks Apps 支持两种互补的授权模型：应用授权和用户授权。应用授权使用应用的专用服务主体，适用于应用自有操作或应向每个用户返回相同结果的体验。用户授权在应由已登录用户的权限管辖操作时使用该用户的身份。大多数生产应用可以同时使用这两种模型，为每个请求路径选择适当的身份。请参阅在 Databricks 应用中配置授权。

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

• 以请求用户身份查询销售和客户数据。
• 遵守 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。除非应用实际使用这些能力，否则不要请求 files、model-serving 或 vector-search。

作用域是能力上限，而不是数据访问的授予。应用必须具有适当的 API 作用域，并且用户仍必须有权访问目标资源。请参阅基于作用域的安全性和权限提升。

为应用配置显式 API 作用域

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

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

注意：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 范围，也可以设置为“无”以禁用用户授权。请参阅限制用户授权范围。

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

将应用拥有的操作与用户拥有的操作分开

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

• 应用范围的客户端，用于写入应用程序指标或读取共享配置。
• 用户范围的客户端，使用 sql:restricted-query 为当前用户查询数据。
• 如果需要在用户的名义下调用另一个 Databricks 服务，则使用单独的用户 API 范围。

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

如果某个请求需要用户授权但转发的令牌缺失，应以失败关闭（fail closed）方式处理，而不是静默切换到应用的服务主体。否则，应用可能返回看似有效但使用不同权限生成的响应。这就是为什么上面示例中的 query_as_user 以 require_user_token 开头，而不是内联处理缺失的标头。

对代理应用同样的模式

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

保护实现安全

• 只请求所需的最低 API 范围。
• 在代码、测试和依赖项接线中将应用拥有的客户端与用户授权的客户端分开。
• 绝不打印、记录或持久化转发的访问令牌。
• 将应用管理限制为受信任的开发者，并要求对与授权相关的更改进行同行评审。
• 将应用授权用于共享和后台操作，而不是保留用户令牌。
• 使用 Unity Catalog 访问权限不同的用户进行测试，然后在策略更改后重复这些测试。

开始使用

代表用户授权让你通过同一机制实现个性化和治理。用户的 Unity Catalog 权限决定应用可以访问哪些数据，而最窄的匹配 API 范围决定应用可以代表他们执行哪些操作。要开始使用，请查看我们的帮助文档以获取更多资源和最佳实践。