教程:用RBAC限定AI代理的访问权限

使用基于角色的访问控制(RBAC)来限制AI代理对特定任务所需数据和资源的访问。 向代理提供一个具有某个角色作用域的 OAuth 令牌。 使用该令牌发出的请求使用角色的权限,而非认证用户或服务主体的更广泛权限。

Scenario

AI支持客服需要工单摘要和状态,但不需要包含个人身份信息(PII)的客户联系方式。 其认证服务主体拥有更广泛的访问权限,可以读取这两个数据集。

在此例中,support.tickets 架构包含票证摘要和状态,但不包含客户 PII。 客户联系方式单独存储在 support.customers.contact_details。

你创建 role-support-agent,授予其对 support.tickets 的读取权限,并授予服务主体对其的“承担”权限。 有了该角色的令牌,代理可以读取支持工单,但无法访问客户联系方式。

该角色可以继承父组的数据权限,目录或模式授权可以应用于其下方的所有表。 在这个例子中,确认这些授权不会让该角色访问客户联系表。 请参阅 权限继承。 更改共享授权会影响其他用户和角色,因此请使用测试工作区,而不是移除其他用户的访问权限。

本教程面向接受你提供的OAuth访问令牌的自定义代理、自托管代理或第三方代理。 对于部署在 Databricks 应用上的代理,可以使用内置的应用或用户授权。 请参阅 代理的身份验证。

Prerequisites

  • 一个支持Unity Catalog的工作区,启用了RBAC。 参见 启用RBAC。
  • 需要账户管理员或工作区管理员权限来创建角色、授予 Assume 权限,并将其分配给工作区。 请参阅谁可以管理组?
  • 对 support 目录的所有权,或对其的 MANAGE 权限。
  • 需要工作区管理员权限,或对示例中使用的 SQL 仓库具有“可管理”权限。
  • 现有的表 support.tickets.open_cases 和 support.customers.contact_details。 使用虚构的测试数据,如有需要,在全文中替换为你自己的名称。
  • 分配给工作区的服务主体,具备 Databricks SQL 访问权限、仓库的“可使用”权限,以及查询这两个表的权限。 它需要一个允许 sql 作用域的 OAuth 机密,用于进行机器对机器 (M2M) 身份验证。 请参阅 步骤 1:创建 OAuth 机密。
  • curl 在一个可信的环境中,你可以请求和测试令牌。
  • 一个审核读取者,能够访问 system.access.audit 以验证智能体在该角色下的活动。 参见 “核实审计归属”。

在这个 OAuth M2M 示例中,使用 Azure Databricks 的托管的服务主体。 Microsoft Entra ID 的托管服务主体使用不同的认证设置。 请参阅 使用 OAuth 授权服务主体访问 Azure Databricks。

步骤 1:创建角色

在这个教程中,创建一个空账户组用作角色。

帐户控制台

  1. 以帐户管理员身份登录到帐户控制台。
  2. 在边栏中,单击“用户管理”。
  3. 在“组”选项卡上,单击“添加组”。
  4. 输入 role-support-agent。 不要添加成员。
  5. 单击“确认”。
  6. 将该组分配到带有 Databricks SQL访问权限的工作区。 请查看 分配一个组到工作区。

工作区管理员设置

  1. 作为工作区管理员,登录测试工作区。
  2. 单击顶部栏中的用户名,然后选择 “设置”。
  3. 单击“ 标识和访问 ”选项卡。
  4. 在组旁边,单击管理。
  5. 点击 添加组,然后 添加新组。
  6. 输入 role-support-agent 并选择 Databricks的SQL访问权限。
  7. 单击 添加。 不要添加成员。

这也会把组分配给工作区,并授予你对该工作区的管理权限。

Databricks 的 SQL 访问权限授予对 Databricks SQL 功能的访问权限,包括仪表盘、查询和 SQL 仓库。 示例中使用了SQL查询。 如果你的代理也需要核心工作区功能,如笔记本、作业、模型或管道,授予工作区访问权限。 请参阅 访问权限。 你在第二步配置数据权限和仓库权限。

在这个例子中,你是单独授予 Assume 权限,而不是将服务主体添加为成员。 成员身份还会将组的权限添加到服务主体自身的身份中。

步骤2:授予该角色支持工单的访问权限

作为目录所有者或在 support 上拥有 MANAGE 的用户,运行:

GRANT USE CATALOG ON CATALOG support TO `role-support-agent`;
GRANT USE SCHEMA, SELECT ON SCHEMA support.tickets TO `role-support-agent`;

作为工作区管理员或拥有仓库管理权限的用户,授予该角色仓库访问权限:

  1. 在工作区侧边栏,点击 SQL 仓库。
  2. 点击Kebab 菜单图标。仓库旁边的 kebab 菜单,然后点击权限。
  3. 添加role-support-agent带有可使用。

模式级SELECT授权适用于support.tickets中所有当前和未来的表和视图。 它不会授予访问 support.customers 或其他模式的权限。 如果要将角色限制为仅适用于一个表,就改为在该表上授予 SELECT。 请参阅在 Unity Catalog 中管理权限。

第 3 步:授予权限以担任该角色

通过任一方法授予服务主体“Assume”权限:

帐户控制台

  1. 作为账户管理员,打开账户控制台,点击 用户管理。
  2. 在 “群组 ”标签页中,点击 role-support-agent。
  3. 点击 权限 标签,然后点击 授权访问。
  4. 搜索并选择服务主体,选择担任,然后点击保存。

工作区管理员设置

  1. 作为对该角色具有管理权限的工作区管理员,在测试工作区中打开 设置>身份和访问权限。
  2. 在“组”旁边,点击“管理”,然后选择role-support-agent。
  3. 点击 权限,然后 授予访问权限。
  4. 搜索并选择服务主体,选择担任,然后点击保存。

步骤4:请求一个角色范围的令牌

在你可信的令牌请求环境中,设置以下环境变量:

  • DATABRICKS_HOST:工作区的URL,包含 https:// 且不带尾部斜杠。
  • CLIENT_ID 以及 CLIENT_SECRET:服务主体的应用 ID 和 OAuth 机密。
  • ROLE_GROUP_ID:role-support-agent 的数字 ID。 账户管理员可以在账户控制台的组URL末尾找到它。 帐户管理员、工作区管理员和组管理员也可以使用帐户组 API 来检索该组的 id。
  • DATABRICKS_SQL_WAREHOUSE_ID:第2步授予的仓库ID。 它位于仓库的 ‌HTTP 路径‌中 /sql/1.0/warehouses/ 的后面。 请参阅获取 Azure Databricks 计算资源的连接详细信息。

请求一个带有 assume_group 参数和 sql OAuth作用域的工作区级令牌。 作用域限制令牌只能使用 SQL API。 该角色的数据权限决定了它可以查询哪些表。 参见 有作用域的 OAuth 密钥。

要请求令牌,请运行:

curl --request POST \
  --url "$DATABRICKS_HOST/oidc/v1/token" \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=sql' \
  --data-urlencode "assume_group=$ROLE_GROUP_ID"

将DATABRICKS_TOKEN设置为响应中的access_token值。 利用该 expires_in 数值来判断何时申请更换。 账户级令牌请求不支持 assume_group。 请参阅担任角色。

步骤5:验证令牌的访问权限

在将令牌提供给代理之前,先在可信环境中进行这些检查。

首先,使用服务主体自身身份的令牌建立基线。 在第4步重复请求,不带 assume_group 参数,并暂时将 DATABRICKS_TOKEN 设置为该令牌。 在此步骤中运行两个查询,并确认它们已成功运行。 然后将 DATABRICKS_TOKEN 重新设为角色范围令牌,并重复这些检查。

查看支持工单

使用角色范围的令牌执行此请求:

curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT * FROM support.tickets.open_cases LIMIT 10\",
    \"wait_timeout\": \"50s\"
  }"

该查询之所以能够成功执行,是因为该角色可以读取 support.tickets。 检查回复 status.state 是否为 SUCCEEDED。 如果是 PENDING 或 RUNNING,则使用返回的 statement_id 以相同令牌检索结果:

curl --request GET \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements/<statement-id>" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN"

参见 语句执行API:在仓库上运行SQL 以获取语句状态和结果处理。

检查对客户PII的访问是否被拒绝

使用相同的角色范围令牌和仓库,运行:

curl --request POST \
  --url "$DATABRICKS_HOST/api/2.0/sql/statements" \
  --header "Authorization: Bearer $DATABRICKS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"warehouse_id\": \"$DATABRICKS_SQL_WAREHOUSE_ID\",
    \"statement\": \"SELECT 1 FROM support.customers.contact_details LIMIT 1\",
    \"wait_timeout\": \"50s\"
  }"

如果语句仍在运行,请按照前一节描述检索结果。 尽管使用服务主体自身的令牌时查询会成功,但在 status.error 中查询会因权限错误而失败。 仅有HTTP成功响应并不意味着查询成功。 缺失的表、过期的令牌或仓库错误并不能证明角色的数据权限配置正确。

检查审计归属

使用具有验证审计归属中所述访问权限的审核读取者。 检查测试查询事件 system.access.audit: identity_metadata.run_as 识别授权角色, run_as_display_name 包含 role-support-agent,并 run_by 识别发起请求的服务主体。 审计数据全天更新,因此近期事件可能不会立即出现。 参见 身份元数据参考。

步骤6:配置代理

配置代理的 Azure Databricks 客户端,使用工作空间 URL 和已验证的角色范围令牌。 只向智能体提供该令牌,不要提供服务主体的 OAuth 机密或未限定作用域的令牌。 角色范围的令牌限制了使用该令牌发出的请求。 它不会移除服务主体在其他会话中的权限。

对于使用 Databricks SDK for Python 的代理,在代理环境中设置 DATABRICKS_HOST 和 DATABRICKS_TOKEN ,然后初始化客户端:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

SDK通过 统一认证从环境中读取令牌。 提供访问令牌并不能给 SDK 请求新令牌所需的凭证。 对于长期运行的代理,安排一个可信组件在令牌到期前请求并提供一个替换的角色作用域令牌。

可选:使用开发者的身份信息

对于使用用户到机器(U2M)身份验证的本地测试,授予参与的开发者对 role-support-agent 的 Assume 权限,就像步骤 3 所示。 开发者如 安装或更新 Databricks CLI 中所述安装 Databricks CLI,然后使用自己的登录凭据和单独的配置文件进行身份验证:

databricks auth login --host <workspace-url> --profile support-agent

开发人员在浏览器中的授权为...下选择 role-support-agent,并单击继续,然后检索该配置文件的令牌:

databricks auth token --profile support-agent

开发者在第5步中将返回的 access_token 用作角色范围查询检查的 DATABRICKS_TOKEN。 这些请求的审计事件将开发者识别为 run_by。 Databricks CLI 返回的令牌已过期。 开发者在需要时会获取新的令牌。 参见API(OAuth访问令牌)。

清理

对于临时测试,完成测试后移除智能体的令牌配置,并撤销为测试创建的“承担”权限。 删除该角色前,检查它是否拥有资产或是否被其他工作负载使用。

后续步骤

Resource Description
基于角色的访问控制 (RBAC) 限制 检查哪些功能不受支持或作为某种角色时表现不同。
切换 RBAC 角色 使用其他支持的方法来承担某个角色。