Databricks 参考模式：嵌入式 AI/BI 仪表盘的逐行安全授权

挑战

将 Databricks AI/BI Dashboard 嵌入面向客户的应用程序相对简单：启用嵌入功能，在后端生成一个作用域令牌，然后使用客户端 SDK 渲染仪表板。基础指南《如何将 Databricks AI/BI Dashboard 嵌入面向客户的应用程序》完整地介绍了这一流程。

更难的问题在于授权：仪表板嵌入后，每个查看者应该看到哪些行？合作伙伴应只看到自己的数据，而内部团队可能只看到自己所在区域的数据。本指南展示如何实施这些规则。

此参考模式结合了多项 Databricks 能力：__aibi_external_value、Unity Catalog 行过滤器和列掩码，以及从身份提供程序（IdP）同步的组。这是一种设计模式，而不是要启用的单一功能。

一本规则手册，两条执行路径

同一份权限表管辖两条路径：通过应用程序访问的嵌入式仪表板，以及 Databricks 用户运行的直接 SQL 查询。

一个具体场景

假设一家公司使用一个共享的“未结应收账款（AR）任务”仪表板来展示三个区域的数据：西部、东部和中部。该仪表板面向两类受众。

• 外部运营合作伙伴，例如 Acme Ops、Bolt Partners 和 Core Logistics，没有 Databricks 登录账号，通过白标门户访问仪表板。每个合作伙伴应只看到自己所在的区域，并且联系邮箱被掩码处理。
• 内部团队是公司的员工，他们登录 Databricks。财务部门需要访问所有区域，而区域运营团队只看到自己所在的区域。他们的访问权限来自身份提供程序组，例如 Okta 或 Entra ID，而不是手动维护的用户列表。

五个查看者共享一个数据集，每个人看到不同的数据切片：Acme Ops、Bolt Partners、Core Logistics、财务部门，以及一个区域运营团队。以下示例重点介绍 Acme 和财务部门；标识符 partner_acme、finance_all 和 West 代表这些示例。Acme 看到西部区域，邮箱被掩码，而财务部门看到全部三个区域的完整数据，两者都来自同一个已发布仪表板。

一张表，一个视图，一个仪表板

访问规则集中在一处，而不是分散在各个仪表板或查询中。为每个客户创建一个仪表板会产生可能失去同步的副本，而在每个查询中重复过滤器则会带来出错的机会。

该模型由三个对象组成：

• 基础表 `open_ar_tasks`为每个 AR 任务保存一行，并标记区域和联系邮箱。

• 权限表是访问权限的唯一事实来源。每一行标识某个作用域可以访问的区域，以及是否应掩码敏感值。viewer_scope 列同时存储外部合作伙伴 ID（例如 partner_acme）和内部组名（例如 finance_all）。

• 安全视图将基础表与权限表连接，因此查看者只能看到有权访问的区域，并在该标志设置时对邮箱进行掩码处理。

在大多数部署中，上游权限系统或应用程序拥有的组到区域映射会填充此表；而不是为每个查看者手动编辑。

这避免了为每个客户创建仪表板，以及在查询中重复过滤器。规则位于一张表中，可以查询、审计和更改，而无需修改仪表板。

按查看者应用时，安全视图只返回该查看者有权访问的内容：

Acme（external_value = partner_acme）：仅西部，联系邮箱被掩码。

财务部门（external_value = finance_all）：全部三个区域，联系邮箱完整显示。

__aibi_external_value 从何而来

后端在生成嵌入令牌时设置此值。它以服务主体身份进行身份验证，并向 Databricks 请求一个带有两个值的作用域令牌：external_viewer_id（用于审计标识查看者）和 external_value（表示查看者的作用域）。Databricks 对令牌进行签名，查看者无法修改嵌入的值，该值以 __aibi_external_value 的形式暴露给仪表板 SQL。由于它持有服务主体的凭据，此后端是一个受信任的服务器端组件，绝不是浏览器，并且这些凭据保存在密钥管理器中，而不是源代码管理中。

关键细节在于查询以谁的身份运行。嵌入查询在配置的发布身份下执行，而不是查看者的 Databricks 身份。

对于外部嵌入，Databricks 建议使用单独的数据权限，并授予服务主体其自己的数据访问权限，以便查询以服务主体身份运行。（使用共享数据权限发布时，查询则以发布者的凭据运行。）然后，视图通过 __aibi_external_value 为每个查看者缩小该访问范围。由于查询以服务主体身份运行，在嵌入路径上，is_account_group_member() 无法识别实际查看仪表板的人。

重要的细节是，external_value 不限于合作伙伴 ID。它可以是后端签署到令牌中的任何作用域，例如外部合作伙伴的 partner_acme，或内部组的 finance_all（其组名）。

由于权限表在同一列中保存合作伙伴 ID 和组名，一个仪表板、一个视图和一个过滤器即可覆盖两者。

由于查看者从不看到或设置已签名的值，查看者无法更改它。未知作用域不匹配任何行，这提供了默认拒绝行为。

同一个视图和同一个过滤器（WHERE viewer_scope = __aibi_external_value) 同时服务于这两类受众。只是该范围的来源不同：

向组授予访问权限，而非个人

组织通常通过从身份提供商同步的组来管理访问。当有人在 Okta 中加入 Finance 组时，其访问权限会自动映射到 finance_all，且不会触及任何数据表。在此示例中，finance_all 映射到每个区域，ops_west 映射到 West 区域。

应用程序如何得知查看者属于哪些组？它不能在嵌入期间依赖 SQL，因为查询以服务主体身份运行，而 is_account_group_member() 会检查错误的身份。应用程序必须在铸造令牌之前，在后端（可以看到查看者）解析查看者的组。

一种选择是在启用了用户授权的 Databricks Apps 上运行应用程序。

对于已登录的内部用户，平台会将可信身份上下文转发到后端，包括查看者的电子邮件和代表（OBO）令牌。后端使用该令牌以查看者身份调用 SCIM /Me 并读取其组。

这种方法不需要服务主体的管理员权限，因为用户是在读取自己的记录。它确实需要用户授权范围，而且 Apps OBO 仍在成熟中，因此在依赖它之前，请针对目标部署进行验证。

如果未找到任何已授权的组，则故障关闭并拒绝铸造令牌，而不是回退到更宽泛的身份（例如原始电子邮件）。

如果查看者属于多个已授权的组，则确定性地解析结果。定义优先级顺序，或在铸造令牌之前将多个组映射到一个规范范围，以便同一查看者始终获得一致的访问权限。

外部合作伙伴更简单。由于没有 Databricks 身份，其范围是登录时分配的固定合作伙伴 ID。相同的令牌，相同的筛选器，无需查找。

一个需要围绕其设计的限制：已签名的令牌携带单个 external_value。如果查看者属于多个具有不同授权的组，一个令牌仍然只能表示一个范围。对于常见的每人一个角色的情况，这没有问题。

对于真正的多组并集，请使用全访问组或下面的直接 SQL 路径，其中行筛选器可以对每个组进行 OR 运算。复合范围（例如 JSON）可以打包到 external_value 中，但随后解析和匹配会移入数据集 SQL，并仍受 1 KB 负载限制的约束。

强化保证

行筛选提供基本行为：每个查看者只能看到自己的行。三个附加层强化了控制，并且这三层都从同一个授权表读取。

按查看者屏蔽敏感列

行级安全决定查看者可以访问哪些行。屏蔽决定他们可以看到哪些列，因为外部合作伙伴通常不需要与内部团队相同级别的详细信息。

mask_pii 标志（对合作伙伴为 true，对内部组为 false）驱动安全视图中的屏蔽逻辑（上面 SQL 中的 CASE 表达式）。同一仪表板可以向内部查看者显示完整的电子邮件，而向合作伙伴显示诸如 ****@example.com 的屏蔽值。当屏蔽规则跨越许多表并变得复杂时，Unity Catalog 列掩码和基于属性的访问控制（ABAC）是更好的长期归宿；在这里，视图使示例保持自包含。

默认拒绝，并证明它

未知范围应返回无仪表板行，并且不应透露任何有关底层数据结构的信息：没有暗示结构的错误，没有部分数据，只有空结果。更早停止则更干净：在后端铸造令牌之前，它会检查授权表并拒绝任何授权为零行的范围。同样重要的是，范围派生自已认证的查看者，而非客户端提供的参数，因此查看者无法请求另一租户的范围。

在令牌颁发时进行门控可防止被拒绝的查看者收到令牌，这胜过仅依赖 SQL 筛选器作为唯一防护。记录成功的令牌颁发和被拒绝的请求可使授权决策可审计：被拒绝的查看者根本不会出现，即使请求溜过，未知范围仍会返回无仪表板行。在这些日志中记录 external_viewer_id 及其范围，可以让每个授权决策在审计期间追溯到真实的客户或用户。

保护直接 SQL 路径

嵌入控制保护应用程序路径。直接查询基表的 Databricks 用户是单独的威胁。向基表添加 Unity Catalog 行筛选器，以查询用户的身份和组为键。在此直接查询路径中，is_account_group_member() 评估实际用户，并且可以合并其所有已授权的组。下面函数中的发布者例外（current_user() 等于发布身份）是对发布或刷新仪表板的身份的有意破窗允许，而非通用操作员绕过。它是可选的且高风险，因此仅在合理的地方包括它，并按部署批准。

敏感字段的列掩码以相同方式工作。这些 Unity Catalog 控制与嵌入路径分开：嵌入的查看者通过 __aibi_external_value 和授权视图进行范围限定，而直接工作区查询由 Unity Catalog 行筛选器保护，该筛选器评估调用者的身份和组。两个执行点使用相同的授权表。

在构建它之前

关于“多租户”。这就是池化、逻辑式多租户：外部合作伙伴彼此隔离，而内部员工在公司自己的租户内获得基于组（基于角色）的访问权限。所有数据仍保留在共享表中；令牌、视图过滤器和权利表共同执行隔离。直接 SQL 行过滤器将同样的保证扩展到应用之外。

何时使用此模式。当没有 Databricks 账户的外部合作伙伴和内部员工需要共享同一个仪表板时，使用此模式。如果每个查看者都是内部 Databricks 用户，那么使用 Unity Catalog 行级和列级安全的基本嵌入可能就足够了。

实际限制和注意事项。在发布前，请对照当前文档核实以下产品限制和操作细节：

• 令牌是短时效的（1 小时），因此应用必须刷新它们，尤其是对于保持打开的标签页。客户端 SDK 让这变得简单：当令牌接近过期时，getNewToken 回调会从 /api/token 端点重新获取。
• 保持 `external_viewer_id` + `external_value` 合计在 1 KB 以下：使用紧凑标识符，而不是 JSON blob 或长电子邮件。
• 每个工作区每秒 20 次仪表板加载的速率限制，适用于外部嵌入。对于大型 B2B 门户来说值得了解。
• 使用非 PII 的 `external_viewer_id`。它会进入审计日志，因此稳定的客户或用户 id 优于全名或原始电子邮件。
• 下载默认开启。除非工作区管理员关闭下载，否则嵌入式查看者可以导出 CSV、TSV、Excel 和 PNG。确认导出的结果与查看者受限的数据预期一致。
• 为直接 SQL 路径配置账户级组。UC 行过滤器和掩码会根据账户级组而非工作区本地组来评估 is_account_group_member()。嵌入路径从不调用该函数。
• 留意大型权利表。对于数千个范围或深层级结构，保持联接和掩码表达式简单，一旦规则变得复杂就依靠 ABAC。

关键要点

• 将访问规则保存在一个权利表中，并将其同时用于嵌入式仪表板和直接 SQL 保护。
• 将查看者或组范围签入 __aibi_external_value；不要依赖用户可编辑的过滤器。
• 使用默认拒绝、掩码和 Unity Catalog 行过滤器作为分层控制。
• 嵌入只是第一步；设计和验证访问控制才是关键工作。

行动号召

从基础指南开始，如何在面向客户的应用中嵌入 Databricks AI/BI 仪表板，然后应用本文中描述的权利、掩码和默认拒绝模式。有关底层治理控制，请参阅 AI/BI 嵌入文档以及 Unity Catalog 行过滤器和列掩码和 ABAC 指南。