使用 IAM Conditions 控制对会话的访问权限

默认情况下，会话 Identity and Access Management 权限位于项目级层。本文档介绍如何使用 IAM Conditions 控制对 Agent Runtime Sessions 资源的更精细访问权限。

概览

IAM Conditions 可让您仅在满足指定条件时才授予对会话和会话事件资源的访问权限。您可以使用 API 特性 aiplatform.googleapis.com/sessionUserId 和以通用表达式语言编写的表达式，根据会话资源中的 userId 字符串控制对会话的访问权限。用户 ID 是创建会话时提供的任意字符串，例如 userId = "userA"。

这些条件性 Identity and Access Management 政策是在项目级层创建的，适用于项目中的所有会话和会话事件。您可以将 IAM Conditions 应用于各种主账号，包括项目的用户和服务账号。

IAM Conditions 可用于同时授予多个相关会话资源（包括尚不存在的资源）的 Identity and Access Management (IAM) 访问权限。您可以限制对会话和事件的访问权限，以便用户只能访问自己的信息，或者开发者只能查看某些会话资源，而无需授予特殊权限。

准备工作

如需为会话和会话事件设置条件性 Identity and Access Management 政策，请执行以下操作：

• 查看 IAM Conditions：熟悉 IAM Conditions 概览。
• 确定必要的角色：确定哪些 专用会话 IAM 角色 适合您的使用场景，以确保遵循最低 权限原则。
• 确定受影响的主账号：确定组织中哪些人应获得哪些权限。例如，请考虑以下事项： 以下事项：
  • 用户是否应该能够查看其他用户的会话？
  • 开发者是否应该能够查看所有会话？
  • 项目管理员是否应该能够查看所有会话？
  • 某些代理身份是否应该能够访问某些会话？
• 授予 IAM 角色：确保您拥有包含执行本文档中的任务所需的必要权限的必要角色。

  如需获得将 IAM Conditions 应用于 Agent Runtime Session 资源所需的权限，请让您的管理员为您授予以下 IAM 角色：

  • 对于项目： 项目 IAM 管理员 (`roles/resourcemanager.projectIamAdmin`)

  如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

  这些预定义角色包含 将 IAM Conditions 应用于 Agent Runtime Session 资源所需的权限 。如需查看所需的确切权限，请展开所需权限部分：

  所需权限

  如需将 IAM Conditions 应用于 Agent Runtime Session 资源，您需要具有以下权限：

  • 在项目级层设置条件性 IAM 访问权限： `resourcemanager.projects.setIamPolicy`

  您也可以使用自定义角色或其他预定义角色来获取这些权限。

  如果您计划在整个组织中使用 IAM Conditions 条件，您 还需要 管理组织政策的权限。

为会话创建条件性访问权限

如需授予对会话的条件性访问权限，请在项目级层向 Identity and Access Management 政策绑定添加条件。该条件使用 api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") 函数检查会话资源的用户 ID。您可以在 创建会话时定义用户 ID。

如需详细了解如何创建具有条件的 IAM 政策，请参阅 允许政策中的条件。

如需向主账号授予单个角色，请执行以下操作：

控制台

1. 在 Google Cloud 控制台中，前往 IAM 页面。

   转到 IAM

2. 选择您的项目。

3. 选择要向其授予一个角色的主账号：

   • 如需向已拥有资源的其他角色的主账号授予角色，请找到包含该主账号的行，点击该行中的 修改主账号 ，然后点击 添加其他角色 。

     如需向 服务 代理授予角色，请选中 包括 Google-提供的角色授权 复选框以查看其 电子邮件地址。

     注意： 管理 资源访问权限时，您无法修改继承的角色。要修改继承的角色，请找到授予角色的资源。

   • 如需向尚未拥有资源的任何现有角色的主账号授予角色，请点击 授予访问权限 ，然后输入 主账号 标识符。例如， 或 //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail]。

4. 从下拉列表中选择要授予的角色。为了获得最佳安全实践，请选择仅包含主账号所需权限的角色。 您可以选择一个专用会话 IAM 角色。

5. 使用 aiplatform.googleapis.com/sessionUserId 作为 API 特性，向角色添加条件。如需查看一些可能的 条件语句，请参阅以下示例。

6. 点击保存 。将向主账号授予资源上的角色。

gcloud

1. 在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。 Google Cloud Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟来完成初始化。

2. add-iam-policy-binding 命令使您可以快速向主账号授予角色。

   在使用以下任何命令数据之前， 请进行以下替换：

   • PROJECT_ID：您的 Google Cloud 项目 ID。项目 ID 是字母数字，例如 my-project。

   • PRINCIPAL：主账号（或成员）的标识符，通常其格式如下：PRINCIPAL_TYPE:ID。例如 或 principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail]。如需查看 PRINCIPAL 可以采用的值的完整列表，请参阅主账号标识符。

   • ROLE_NAME：要撤消的角色的名称。请采用以下某种格式：

     • 预定义角色：roles/aiplatform.IDENTIFIER
     • 项目级自定义角色：projects/PROJECT_ID/roles/IDENTIFIER

     从下拉列表中选择要授予的角色。为了获得最佳安全实践， 请选择仅包含主账号所需权限的角色。 您可以选择一个 专用会话 IAM 角色。

   • CONDITION：使用 aiplatform.googleapis.com/sessionUserId 作为 API 特性，向角色添加条件。 如需查看一些可能的条件语句，请参阅以下 示例。

   执行以下命令：

   Linux、macOS 或 Cloud Shell

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=PRINCIPAL --role=ROLE_NAME \
       --condition=CONDITION

   Windows (PowerShell)

   gcloud projects add-iam-policy-binding PROJECT_ID `
       --member=PRINCIPAL --role=ROLE_NAME `
       --condition=CONDITION

   Windows (cmd.exe)

   gcloud projects add-iam-policy-binding PROJECT_ID ^
       --member=PRINCIPAL --role=ROLE_NAME ^
       --condition=CONDITION

   响应中包含更新后的 IAM 政策。

Terraform

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

如果您使用 Terraform 设置 IAM 政策，则可以在条件 中添加 google_project_iam_member 资源，以限制成员对会话的访问权限。

resource "google_project_iam_member" "example" {
  project    = "PROJECT_ID"
  role       = "ROLE"
  member     = "MEMBER"
  condition {
    title       = "Session Access Condition"
    description = "IAM condition for Session"
    expression  = "CONDITION"
  }
}

执行以下变量替换操作：

• PROJECT_ID：您的 Google Cloud 项目 ID。 项目 ID 是字母数字，例如 my-project。
• ROLE：要授予的 IAM 角色，例如 roles/aiplatform.sessionEditor。
• MEMBER：要向其授予角色的主账号，例如 user:[e-mail]。如需查看 MEMBER 可以采用的值的完整列表，请参阅 主账号标识符。
• CONDITION：您的 IAM 条件语句，使用 aiplatform.googleapis.com/sessionUserId 作为 API 特性。 如需查看一些可能的条件 语句，请参阅以下示例。

用户 ID 级权限的最佳实践

为会话构建条件时，请遵循以下最佳实践：

1. 使用专用会话 IAM 角色：会话 IAM Conditions 仅应用于适用于会话和会话事件的角色。您可以使用专用角色（例如 aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionEditor 和 aiplatform.googleapis.com/sessionUser）来防止过于宽松的访问权限。 如需了解详情，请参阅专用会话 IAM 角色 部分。

2. 使用肯定条件：我们建议对 aiplatform.googleapis.com/sessionUserId 使用肯定条件（例如 检查相等性或是否存在前缀），以提高准确性。由于不受支持的类型和服务由空用户 ID 表示，因此否定条件（例如检查不相等性）可能会无意中匹配大量资源，这可能会过于宽松并允许意外授予权限。

3. 尽可能缩短条件：我们建议在 IAM 条件表达式中使用最短、最简单的逻辑，尤其是在您计划使用大量条件的情况下。IAM 允许政策具有大小限制，简化条件将有助于避免超出 IAM 限制。如需了解详情，请参阅 限制。例如，您可以简化 对两个不同用户 ID 的检查，方法是将复合语句： api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB'合并为较短的 语句 api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['sessionA', 'sessionB']，因为它们评估的结果相同。

专用会话 IAM 角色

使用 IAM Conditions 时，防止 IAM 政策过于宽松至关重要。下表列出了在为会话 API 授予条件性 IAM 角色时可以使用的专用角色：

角色名称	说明	包含的权限
roles/aiplatform.sessionViewer	授予对会话和列表事件的只读权限。	aiplatform.googleapis.com/sessions.get aiplatform.googleapis.com/sessions.list aiplatform.googleapis.com/sessionEvents.list
roles/aiplatform.sessionEditor	授予对会话的写入权限和附加事件的权限。	aiplatform.googleapis.com/sessions.create aiplatform.googleapis.com/sessions.update aiplatform.googleapis.com/sessions.delete aiplatform.googleapis.com/sessionEvents.append
roles/aiplatform.sessionUser	授予对会话和事件的完整访问权限，包括所有查看者和编辑器 权限。	包含 sessionEditor 和 sessionViewer 的所有权限。

将 IAM Conditions 与会话搭配使用

本部分介绍了将 IAM Conditions 与会话搭配使用的以下示例：

1. 授予对用户 ID 完全匹配的会话的读取权限。

2. 授予对用户 ID 中包含特定前缀的会话的写入权限。

3. 授予对包含两个用户 ID 之一的会话的完整访问权限。

授予对用户 ID 完全匹配的会话的读取权限

以下条件仅向个人 [e-mail] 授予对用户 ID 完全为 userA 的会话的查看权限。

这意味着，只要用户 ID 完全为 userA，该个人就能够获取会话并列出相应会话事件。该用户无权访问用户 ID 为 userB 等的会话。

{
  "members": ["user:[e-mail]"],
  "role": "roles/aiplatform.sessionViewer",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'userA'"
  }
}

授予对用户 ID 中包含特定前缀的会话的写入权限

以下条件向个人 [e-mail] 授予对包含以 user 开头的用户 ID 的任何会话的修改权限。您可以使用 startsWith 进行前缀检查，使用 endsWith 进行后缀检查。

这意味着，开发者能够创建、更新和删除会话，以及附加事件，用户 ID 为 userA 或 user1234 等。

{
  "members": ["user:[e-mail]"],
  "role": "roles/aiplatform.sessionEditor",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '').startsWith('user')"
  }
}

授予对包含两个用户 ID 之一的会话的完整访问权限

以下条件向群组 group:[e-mail] 用户（查看者和编辑器）授予对仅具有用户 ID userA 或 user123 的会话的访问权限。

{
  "members": ["group:[e-mail]"],
  "role": "roles/aiplatform.sessionUser",
  "condition": {
    "title": "Session Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') in ['userA', 'user123']"
  }
}

限制

1. 主账号限制：IAM 政策最多只能包含 1500 个唯一 主账号。您可以使用 Google 群组来管理此限制。如需了解详情，请参阅 针对所有 主账号的限制。

2. ListSessions API 支持 ：ListSessions API 不支持 IAM 条件。如需授予 ListSessions 权限，您必须向主账号授予无条件角色，例如 aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionUser 或相关的无条件 Gemini Enterprise Agent Platform 角色。