使用 IAM Conditions 控制对记忆库的访问权限

借助记忆库，您可以根据记忆和记忆修订版本的范围属性来控制对这些资源的访问权限。您可以使用 IAM Conditions 定义精细的访问权限控制，例如根据通用表达式语言中定义的条件限制对特定用户或群组的访问权限。

本文档介绍了如何在项目中为记忆和修订版本创建和应用条件访问权限政策。

如需了解权限概览，请参阅查看必要角色。

概览

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

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

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

准备工作

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

• 查看 IAM Conditions：熟悉 IAM Conditions 概览。
• 确定必要角色：确定哪些专用记忆库 IAM 角色适合您的使用场景，以确保遵循 最小权限原则。

• 确定受影响的主账号：确定组织中的哪些人应获得哪些权限。例如，请考虑以下事项： 以下事项：

  • 开发者是否应能够查看所有记忆。
  • 项目管理员是否应能够查看所有记忆。
  • 某些代理身份是否只能访问某些记忆。
• 授予 IAM 角色：确保您拥有包含执行本文档中的任务所需的必要权限的角色。

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

  • 对于项目： Project IAM Admin (`roles/resourcemanager.projectIamAdmin`)

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

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

  所需权限

  您需要具备以下权限才能 应用 IAM Conditions 应用于 Agent Platform 记忆库资源：

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

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

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

为记忆创建条件访问权限

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

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

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

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"
  }
}

范围级权限的最佳实践

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

1. 使用专用记忆库角色: 记忆库 IAM Conditions 只能用于适用于记忆和记忆修订版本的角色 。您可以使用专用角色（例如 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor 和 aiplatform.googleapis.com/memoryUser）来防止过于宽松的访问权限。 如需了解详情，请参阅专用记忆库 IAM 角色。

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

3. 尽可能缩短条件：我们建议在 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 Conditions 时，防止 IAM 政策过于宽松至关重要。下表列出了在为记忆库 API 授予条件 IAM 角色时可以使用的专用角色：

将 IAM Conditions 与记忆库搭配使用

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

1. 授予对具有完全匹配范围的记忆的读取权限。

2. 授予对具有包含特定键值对的范围的记忆的写入权限。

3. 授予对具有包含特定键的范围的记忆的完整访问权限。

4. 授予对具有包含特定前缀的范围的记忆的完整访问权限。

5. 授予对具有包含一组允许值的键的范围的记忆的完整访问权限。

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

以下条件仅向个人 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'`）的记忆的访问权限。'userA''userB'

这意味着，群组成员拥有对具有 以下范围的记忆的完整读写权限：{'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'] in ['userA', 'userB']"
  }
}

限制

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

• API 支持：IAM Conditions 不受针对多个范围运行的方法（例如ListMemories和PurgeMemories）的支持。如需授予这些权限，您必须向主账号授予无条件角色，例如 aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryUser 或相关的无条件 Gemini Enterprise Agent Platform 角色。