IAM 条件を使用してメモリバンクへのアクセスを制御する

Memory Bank では、スコープ属性に基づいてメモリとメモリ リビジョン リソースへのアクセスを制御できます。IAM 条件を使用すると、Common Expression Language で定義された条件に基づいて特定のユーザーまたはグループへのアクセスを制限するなど、きめ細かいアクセス制御を定義できます。

このドキュメントでは、プロジェクトのメモリとリビジョンに対して条件付きアクセス ポリシーを作成して適用する方法について説明します。

権限の概要については、必要なロールを確認するをご覧ください。

概要

IAM Conditions では、指定された条件が満たされた場合にのみ、メモリとメモリ リビジョン リソースへのアクセスを許可できます。API 属性 "aiplatform.googleapis.com/memoryScope" と Common Expression Language で記述された式を使用して、メモリ リソース内の scope フィールドに基づいてメモリへのアクセスを制御できます。スコープは、メモリの作成時または生成時に指定される任意の辞書（{'user_id': '123'} など）です。これにより、どのメモリがどのグループに属するかを整理できます。

これらの条件付き Identity and Access Management ポリシーはプロジェクト レベルで作成され、プロジェクト内のすべてのメモリに適用されます。IAM 条件は、プロジェクトのユーザーやサービス アカウントなど、あらゆる種類のプリンシパルに適用できます。

IAM Conditions は、まだ存在しないリソースを含め、関連する多くのメモリバンク リソースに Identity and Access Management（IAM）権限を同時に付与する場合に役立ちます。ユーザーが自分の情報にのみアクセスできるように、またはデベロッパーが特別な権限付与なしで特定のメモリバンク リソースのみを表示できるように、メモリとリビジョンへのアクセスを制限できます。

始める前に

メモとメモのリビジョンに条件付き IAM ポリシーを設定する手順は次のとおりです。

• IAM Conditions を確認する: IAM Conditions の概要を理解します。
• 必要なロールを特定する: 最小権限の原則を確保するために、ユースケースに適した専用の Memory Bank IAM ロールを特定します。

• 影響を受けるプリンシパルを特定する: 組織内のどのユーザーにどの権限を付与するかを特定します。たとえば、次の点を考慮します。

  • デベロッパーがすべての思い出を表示できるかどうか。
  • プロジェクト管理者がすべてのメモリーを表示できるかどうか。
  • 特定のエージェント ID が特定のメモリにのみアクセスできるかどうか。
• IAM ロールを付与する: このドキュメントのタスクを実行するために必要な権限を含む必要なロールがあることを確認します。

  Agent Platform メモリバンク リソースに IAM 条件を適用するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • プロジェクトの場合: プロジェクト IAM 管理者（`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 ポリシーの作成に関する詳細なガイドについては、許可ポリシーの条件をご覧ください。

プリンシパルに 1 つのロールを付与する方法は次のとおりです。

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 条件は、メモリと記憶リビジョンに適用されるロールにのみ使用する必要があります。aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor、aiplatform.googleapis.com/memoryUser などの特別なロールを使用して、過度に制限のないアクセスを防ぐことができます。詳細については、Specialized Memory Bank IAM ロールをご覧ください。

2. 肯定的な条件を使用する: 精度を高めるには、aiplatform.googleapis.com/memoryScope で肯定的な条件（等価性のチェックや Key-Value ペアの存在など）を使用することをおすすめします。サポートされていないタイプとサービスは空のスコープで表されるため、否定条件（不等号のチェックなど）は幅広いリソースに誤って一致する可能性があります。これにより、過剰な権限が付与され、予期しない権限付与が可能になる可能性があります。

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 条件を使用する場合は、過剰な権限を付与する IAM ポリシーを防ぐことが重要です。次の表に、メモリバンク API の条件付き IAM ロールを付与するときに使用できる特殊なロールを示します。

メモリバンクでの IAM Conditions の使用

このセクションでは、Memory Bank で IAM Conditions を使用する次の例について説明します。

1. スコープが完全に一致する思い出への読み取り権限を付与します。

2. 特定の Key-Value ペアを含むスコープでメモリーへの書き込みアクセス権を付与します。

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

特定の Key-Value ペアを含むスコープでメモリーへの書き込みアクセス権を付与

次の条件では、Key-Value ペア 'userId': 'userA' を含むすべてのメモリに対する個々の developerA@corp.com 編集アクセス権が付与されます。

つまり、ユーザーは {'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' のいずれかであるメモリーへのアクセス権が付与されます。

つまり、グループのメンバーは、{'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 ポリシーは、1,500 個の一意のプリンシパルに制限されます。この上限は、Google グループを使用して管理できます。詳細については、すべてのプリンシパルの上限をご覧ください。

• API のサポート: IAM 条件は、ListMemories や PurgeMemories など、複数のスコープに対して動作するメソッドではサポートされていません。これらの権限を付与するには、プリンシパルに aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryUser、または関連する無条件の Gemini Enterprise Agent Platform ロールなどの無条件のロールを付与する必要があります。