IAM Conditions を使用して Memory Bank へのアクセスを制御する

デフォルトでは、メモリの Identity and Access Management 権限はプロジェクトレベルです。このドキュメントでは、IAM Conditions を使用して、Vertex AI Agent Engine Memory Bank リソースへのアクセスをより詳細に制御する方法について説明します。

概要

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

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

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

始める前に

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

IAM Conditions を確認する: IAM Conditions の概要を理解します。
必要なロールを決定する: 最小権限の原則を確保するために、ユースケースに適した専用の Memory Bank IAM ロールを特定します。
影響を受けるプリンシパルを特定する: 組織内のどのユーザーにどの権限を付与するかを特定します。たとえば、次の例について考えてみます。
- デベロッパーがすべてのメモリーを表示できるかどうか。
- プロジェクト管理者がすべての思い出を表示できるかどうか。
- 特定のエージェント ID が特定のメモリにのみアクセスできるかどうか。
IAM ロールを付与する: このドキュメントのタスクを実行するために必要な権限を含む必要なロールが付与されていることを確認します。
Vertex AI Agent Engine Memory Bank リソースに IAM Conditions を適用するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
- プロジェクトの場合: プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、IAM Conditions を Vertex AI Agent Engine メモリバンクリソースに適用するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限

IAM Conditions を Vertex AI Agent Engine Memory Bank リソースに適用するには、次の権限が必要です。
- プロジェクトレベルで条件付き IAM アクセス権を設定します。 resourcemanager.projects.setIamPolicy
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
組織全体で IAM Conditions を使用する場合は、組織のポリシーを管理する権限も必要です。

思い出の条件付きアクセスを作成する

メモリへの条件付きアクセス権は、プロジェクトレベルで IAM ポリシーバインディングに条件を追加することで付与されます。この条件では、api.getAttribute('aiplatform.googleapis.com/memoryScope', {}) 関数を使用してメモリリソースのスコープマップを検査します。スコープは、メモリの作成時または生成時に定義します。

条件付きの IAM ポリシーの作成に関する詳細なガイドについては、許可ポリシーの条件をご覧ください。

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

コンソール

Google Cloud コンソールで、[IAM] ページに移動します。

[IAM] に移動
プロジェクトを選択します。
ロールを付与するプリンシパルを選択します。
- リソースに対する他のロールをすでに持っているプリンシパルにロールを付与するには、プリンシパルを含む行を見つけて、その行で [プリンシパルを編集] をクリックし、[別のロールを追加] をクリックします。
  
  サービスエージェントにロールを付与するには、[Google提供のロール付与を含みます] チェックボックスをオンにして、メールアドレスを表示します。
  
  注: リソースへのアクセスを管理するときに、継承されたロールの編集を行うことはできません。継承されたロールを編集するには、ロールが付与されたリソースに移動します。
- リソースに対する既存のロールを持たないプリンシパルにロールを付与するには、 [アクセスを許可] をクリックし、プリンシパル ID（my-user@example.com や //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com など）を入力します。
付与するロールをプルダウンリストから選択します。セキュリティのベストプラクティスに沿って、プリンシパルが必要とする権限のみを含むロールを選択してください。Memory Bank の特別な IAM ロールのいずれかを選択できます。
API 属性として aiplatform.googleapis.com/memoryScope を使用して、ロールに条件を追加します。条件ステートメントの例については、下記の例をご覧ください。
[保存] をクリックします。リソースのロールがプリンシパルに付与されます。

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 に使用できる値の一覧については、プリンシパル ID をご覧ください。
  
  プリンシパルタイプが user の場合、識別子に含まれるドメイン名は Google Workspace ドメインまたは Cloud Identity ドメインである必要があります。Cloud Identity ドメインの設定方法については、Cloud Identity の概要をご覧ください。
- ROLE_NAME: 取り消すロールの名前。次のいずれかの形式で指定してください。
  - 事前定義ロール: roles/aiplatform.IDENTIFIER
  - プロジェクトレベルのカスタムロール: projects/PROJECT_ID/roles/IDENTIFIER
  付与するロールをプルダウンリストから選択します。セキュリティのベストプラクティスに沿って、プリンシパルが必要とする権限のみを含むロールを選択してください。Memory Bank の特別な IAM ロールのいずれかを選択できます。
- CONDITION: API 属性として aiplatform.googleapis.com/memoryScope を使用して、ロールに条件を追加します。可能な条件ステートメントについては、以下の例をご覧ください。
次のコマンドを実行します。
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 に使用できる値の一覧については、プリンシパル ID をご覧ください。
CONDITION: API 属性として aiplatform.googleapis.com/memoryScope を使用する IAM 条件ステートメント。条件ステートメントの例については、下記の例をご覧ください。

スコープレベルの権限に関するベストプラクティス

Memory Bank の条件を作成する場合は、次のベストプラクティスを使用します。

専用の Memory Bank ロールを使用する: Memory Bank IAM 条件は、メモリとメモリリビジョンに適用されるロールにのみ使用する必要があります。aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryEditor、aiplatform.googleapis.com/memoryUser などの特別なロールを使用して、過度に許可されたアクセスを防ぐことができます。詳細については、Specialized Memory Bank 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' と同じ結果になるためです。

専用のメモリバンク IAM ロール

IAM Conditions を使用する場合は、過剰な権限を付与する 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` の両方のすべての権限が含まれます。

Memory Bank で IAM Conditions を使用する

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

スコープが完全に一致する思い出への読み取り権限を付与します。
特定の Key-Value ペアを含むスコープでメモリーへの書き込みアクセス権を付与します。
特定のキーを含むスコープで思い出へのフルアクセス権を付与します。
特定の接頭辞を含むスコープでメモリーへのフルアクセス権を付与します。
許可された値のセットを含むキーのスコープで、メモリーへのフルアクセス権を付与します。

スコープが完全に一致するメモリへの読み取りアクセス権を付与

次の条件では、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'"
  }
}

特定のキーを含むスコープでメモリーへの完全アクセス権を付与

次の条件では、キー 'admin_override' または 'public_access_flag' を持つメモリーへのアクセス権（閲覧者と編集者）がグループ group:engineering@corp.com ユーザーに付与されます。

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

{
  "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 グループを使用して管理できます。詳細については、すべてのプリンシパルの上限をご覧ください。
ListMemories API のサポート: ListMemories API は IAM 条件をサポートしていません。ListMemories 権限を付与するには、プリンシパルに aiplatform.googleapis.com/memoryViewer、aiplatform.googleapis.com/memoryUser などの無条件ロール、または関連する無条件の Vertex AI ロールを付与する必要があります。