使用 IAM Conditions 控制对内存库的访问权限

默认情况下，内存 Identity and Access Management 权限位于项目级层。本文档介绍了如何使用 IAM Conditions 来更精细地控制对 Vertex AI Agent Engine 记忆库资源的访问权限。

概览

借助 IAM Conditions，您可以仅在满足指定条件时才授予对内存和内存修订版资源的访问权限。您可以使用 API 属性 "aiplatform.googleapis.com/memoryScope" 和以通用表达式语言编写的表达式，根据记忆资源中的 scope 字段来控制对记忆的访问权限。范围是一个任意字典，在创建或生成记忆时提供，例如 {'user_id': '123'}，可用于组织哪些记忆属于哪个组。

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

IAM Conditions 条件可用于同时授予多个相关 Memory Bank 资源的 Identity and Access Management (IAM) 权限，包括尚不存在的资源。您可以限制对记忆和修订版本的访问权限，以便用户只能访问自己的信息，或者开发者只能查看某些记忆库资源，而无需获得特殊权限。

准备工作

如需为记忆和记忆修订版本设置条件性 IAM 政策，请执行以下操作：

查看 IAM Conditions：熟悉 IAM Conditions 概览。
确定必要的角色：确定哪些专用内存库 IAM 角色适合您的使用情形，以确保遵循最小权限原则。
确定受影响的主账号：确定组织中的哪些人应获得哪些权限。例如，请考虑以下情况：
- 开发者是否应能够查看所有回忆。
- 项目管理员是否应能够查看所有回忆。
- 某些代理身份是否只能访问某些记忆。
授予 IAM 角色：确保您拥有包含执行本文档中的任务所需的必要权限的角色。 <0x
如需获得将 IAM 条件应用于 Vertex AI Agent Engine 记忆库资源所需的权限，请让您的管理员为您授予以下 IAM 角色：
- 对于项目： Project IAM Admin (roles/resourcemanager.projectIamAdmin)
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

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

如需将 IAM Conditions 应用于 Vertex AI Agent Engine 记忆库资源，您需要具有以下权限：
- 在项目级层设置有条件的 IAM 访问权限： resourcemanager.projects.setIamPolicy
您也可以使用自定义角色或其他预定义角色来获取这些权限。
如果您计划在整个组织中使用 IAM Conditions 条件，则还需要管理组织政策的权限。

为回忆创建条件访问权限

如需授予对记忆的有条件访问权限，请在项目级层向 IAM 政策绑定添加条件。该条件使用 api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) 函数来检查内存资源的范围映射。您可以在创建或生成记忆时定义范围。

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

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

控制台

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

转到 IAM
选择您的项目。
选择要向其授予一个角色的主账号：
- 如需向已拥有资源的其他角色的主账号授予角色，请找到包含主账号的行，点击该行中的 修改主账号，然后点击 添加其他角色。
  
  如需向服务代理授予角色，请选中包括Google提供的角色授权复选框以查看其电子邮件地址。
  
  注意：管理资源访问权限时，您无法修改继承的角色。要修改继承的角色，请找到授予角色的资源。
- 如需向尚未拥有资源的任何现有角色的主账号授予角色，请点击 授予访问权限，然后输入主账号标识符，例如 my-user@example.com 或 //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。
从下拉列表中选择要授予的角色。出于最佳安全做法考虑，请选择一个仅包含主账号所需权限的角色。您可以选择一个专门的记忆库 IAM 角色。
使用 aiplatform.googleapis.com/memoryScope 作为 API 属性，为角色添加条件。如需查看一些可能的条件语句，请参阅以下示例。
点击保存。将向主账号授予资源上的角色。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
add-iam-policy-binding 命令使您可以快速向主账号授予角色。

在使用下面的命令数据之前，请先进行以下替换：
- PROJECT_ID：您的 Google Cloud 项目 ID。项目 ID 为字母数字，例如 my-project。
- PRINCIPAL：主账号（或成员）的标识符，通常其格式如下：PRINCIPAL_TYPE:ID。例如 user:my-user@example.com 或 principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com。如需查看 PRINCIPAL 可以采用的值的完整列表，请参阅主账号标识符。
  
  对于主账号类型 user，标识符中的域名必须是 Google Workspace 网域或 Cloud Identity 网域。如需了解如何设置 Cloud Identity 网域，请参阅 Cloud Identity 概览。
- ROLE_NAME：要撤消的角色的名称。请采用以下某种格式：
  - 预定义角色：roles/aiplatform.IDENTIFIER
  - 项目级自定义角色：projects/PROJECT_ID/roles/IDENTIFIER
  从下拉列表中选择要授予的角色。出于最佳安全做法考虑，请选择一个仅包含主账号所需权限的角色。您可以选择一个专门的记忆库 IAM 角色。
- CONDITION：使用 aiplatform.googleapis.com/memoryScope 作为 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       = "Memory Access Condition"
    description = "IAM condition for Memory Bank"
    expression  = "CONDITION"
  }
}

替换以下变量：

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

范围级权限的最佳实践

为记忆库构建条件时，请遵循以下最佳实践：

使用专门的记忆库角色：记忆库 IAM 条件应仅用于适用于记忆和记忆修订的角色。您可以使用 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor 和 aiplatform.googleapis.com/memoryUser 等专业角色来防止访问权限过于宽松。如需了解详情，请参阅专用内存库 IAM 角色。
使用正向条件：建议对 aiplatform.googleapis.com/memoryScope 使用正向条件（例如检查是否相等或是否存在键值对），以提高准确性。由于不受支持的类型和服务由空范围表示，因此否定条件（例如不相等性检查）可能会无意中匹配各种资源，这可能会过于宽松，并允许授予意外的权限。
尽可能缩短条件：我们建议在 IAM 条件表达式中使用最短、最简单的逻辑，尤其是在您计划使用大量条件的情况下。IAM 允许政策的大小有限制，简化条件可防止遇到这些 IAM 限制。如需了解详情，请参阅限制。例如，您可以省略对表达式 'user_id' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) && api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA' 中是否存在键的检查，而改用较短的语句 api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['user_id'] == 'userA'。如果缺少 user_id 键，较长的表达式的计算结果为 false，而较短的表达式会导致错误。由于 IAM 条件表达式中的错误会导致访问权限被拒绝，因此这两个表达式会产生相同的结果。

专用记忆库 IAM 角色

使用 IAM 条件时，务必要防止 IAM 政策过于宽松。下表列出了在为 Memory Bank API 授予有条件 IAM 角色时可以使用的专用角色：

角色名称	说明	包含的权限
`roles/aiplatform.memoryViewer`	授予对记忆和记忆修订版本的只读权限。	`aiplatform.googleapis.com/memories.get` `aiplatform.googleapis.com/memories.list` `aiplatform.googleapis.com/memories.retrieve` `aiplatform.googleapis.com/memoryRevisions.list` `aiplatform.googleapis.com/memoryRevisions.get`
`roles/aiplatform.memoryEditor`	授予对记忆的写入和生成权限，以及对记忆修订版本的回滚权限。	`aiplatform.googleapis.com/memories.create` `aiplatform.googleapis.com/memories.update` `aiplatform.googleapis.com/memories.delete` `aiplatform.googleapis.com/memories.generate` `aiplatform.googleapis.com/memoryRevisions.rollback`
`roles/aiplatform.memoryUser`	授予对记忆和修订版本的完整访问权限，包括所有查看者和编辑者权限。	包含 `memoryEditor` 和 `memoryViewer` 的所有权限。

将 IAM 条件与记忆库搭配使用

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

授予对具有完全匹配范围的回忆的读取权限。
授予对包含特定键值对的内存的写入权限。
授予对包含特定键的回忆的完全访问权限。
授予对包含特定前缀的范围内的记忆的完全访问权限。
授予对内存的完整访问权限，并指定键的范围和一组允许的值。

授予对具有完全匹配范围的记忆的读取访问权限

以下条件授予个人用户 userA@gmail.com 视图访问权限，但仅限于范围为 {"userId": "userA"} 的回忆。

这意味着，只要范围为 {"userId": "userA"}，会员就可以获取和检索记忆，以及列出和获取这些记忆的修订版本。用户无权访问范围为 {'userId': 'userA', 'source': 'ADK'} 等的记忆。

{
  "members": ["user:userA@gmail.com"],
  "role": "roles/aiplatform.memoryViewer",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) == {'userId': 'userA'}"
  }
}

授予对包含特定键值对的记忆的写入权限

以下条件授予个人 developerA@corp.com 对包含键值对 'userId': 'userA' 的任何记忆的修改权限。

这意味着，用户能够创建、更新、删除和生成记忆，以及创建和回滚这些记忆的修订版本，范围包括 {'userId': 'userA'} 和 {'userId': 'userA', 'source': 'ADK'}。

{
  "members": ["user:developerA@corp.com"],
  "role": "roles/aiplatform.memoryEditor",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'] == 'userA'"
  }
}

授予对包含特定键的范围内的记忆的完整访问权限

以下条件授予群组 group:engineering@corp.com 用户（查看者和编辑者）对具有键 'admin_override' 或 'public_access_flag' 的记忆的访问权限。

这意味着，群组成员对范围为 {'admin_override': 'true'}、{'admin_override': 'true', 'public_access_flag': 'false'} 和 {'userId': 'userA', 'public_access_flag': 'false'} 的回忆拥有完整的读写权限。

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "('admin_override' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {})) || ('public_access_flag' in api.getAttribute('aiplatform.googleapis.com/memoryScope', {}))"
  }
}

授予对包含特定前缀的范围内的回忆的完整访问权限

以下条件授予群组 group:engineering@corp.com 用户（查看者和编辑者）对具有键 'userId' 且值以 'user' 开头的记忆的访问权限。您可以使用 'startsWith' 进行前缀检查，使用 'endsWith' 进行后缀检查。

这意味着，群组成员对范围为 {'userId': 'userA'}、{'userId': 'userB', 'public_access_flag': 'false'} 等的回忆具有完整的读写权限。

{
  "members": ["group:engineering@corp.com"],
  "role": "roles/aiplatform.memoryUser",
  "condition": {
    "title": "Memory Access Condition",
    "expression": "api.getAttribute('aiplatform.googleapis.com/memoryScope', {})['userId'].startsWith('user')"
  }
}

授予对内存的完整访问权限，并使用一组允许的值来限定密钥的范围

以下条件授予群组 group:engineering@corp.com 用户（查看者和编辑者）对具有键 'userId' 且值为 'userA' 或 'userB' 的记忆的访问权限。