IAM Conditions を使用してセッションへのアクセスを制御する

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

概要

IAM Conditions では、指定された条件が満たされた場合にのみ、セッションとセッションイベントのリソースへのアクセスを許可できます。Common Expression Language で記述された式を含む API 属性 aiplatform.googleapis.com/sessionUserId を使用して、Session リソース内の userId 文字列に基づいてセッションへのアクセスを制御できます。ユーザー ID は、セッションの作成時に指定される任意の文字列です（例: userId = "userA"）。

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

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

始める前に

セッションとセッションイベントの条件付き Identity and Access Management ポリシーを設定するには、次の操作を行います。

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

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

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

セッションの条件付きアクセスを作成する

プロジェクトレベルで Identity and Access Management ポリシーバインディングに条件を追加して、セッションへの条件付きアクセスを許可します。この条件では、api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") 関数を使用してセッションリソースのユーザー ID を検査します。ユーザー ID は、セッションを作成するときに定義します。

条件付きの 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 など）を入力します。
付与するロールをプルダウンリストから選択します。セキュリティのベストプラクティスに沿って、プリンシパルが必要とする権限のみを含むロールを選択してください。セッションの特別な IAM ロールのいずれかを選択できます。
API 属性として aiplatform.googleapis.com/sessionUserId を使用して、ロールに条件を追加します。条件ステートメントの例については、下記の例をご覧ください。
[保存] をクリックします。リソースのロールがプリンシパルに付与されます。

gcloud

Google Cloud コンソールで Cloud Shell をアクティブにします。

Cloud Shell をアクティブにする

Google Cloud コンソールの下部にある Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
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
  付与するロールをプルダウンリストから選択します。セキュリティのベストプラクティスに沿って、プリンシパルが必要とする権限のみを含むロールを選択してください。専用のセッション IAM ロールのいずれかを選択できます。
- CONDITION: API 属性として aiplatform.googleapis.com/sessionUserId を使用して、ロールに条件を追加します。条件ステートメントの例については、下記の例をご覧ください。
次のコマンドを実行します。
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:developerA@corp.com など）。MEMBER に使用できる値の一覧については、プリンシパル ID をご覧ください。
CONDITION: API 属性として aiplatform.googleapis.com/sessionUserId を使用する IAM 条件ステートメント。条件ステートメントの例については、下記の例をご覧ください。

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

セッションの条件を作成する場合は、次のベストプラクティスを使用します。

専用のセッション IAM ロールを使用する: セッション IAM 条件は、セッションとセッションイベントに適用されるロールにのみ使用する必要があります。aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionEditor、aiplatform.googleapis.com/sessionUser などの特別なロールを使用して、過度に権限のあるアクセスを防ぐことができます。詳細については、専用セッション IAM ロールをご覧ください。
肯定的な条件を使用する: 精度を高めるには、aiplatform.googleapis.com/sessionUserId で肯定的な条件（等価性のチェックや接頭辞の有無のチェックなど）を使用することをおすすめします。サポートされていないタイプとサービスは空のユーザー ID で表されるため、否定条件（不等号のチェックなど）は幅広いリソースに誤って一致する可能性があります。これは過剰な権限付与につながり、予期しない権限付与を許容する可能性があります。
可能な限り条件を短くする: 特に大量の条件を設定する場合は、IAM 条件式内で最も短くシンプルなロジックを使用することをおすすめします。IAM 許可ポリシーにはサイズ制限があります。条件を簡素化すると、IAM の制限に達するのを防ぐことができます。詳細については、制限事項をご覧ください。たとえば、複合ステートメント api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == 'sessionA' || api.getAttribute('aiplatform.googleapis.com/sessionUserId', '') == sessionB' を使用すると、2 つの異なるユーザー ID のチェックを簡素化できます。これは、短いステートメント 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 条件を使用する次の例について説明します。

ユーザー ID が完全に一致するセッションへの読み取り権限を付与します。
ユーザー ID に特定の接頭辞が含まれるセッションへの書き込みアクセス権を付与します。
2 つのユーザー ID のいずれかを含むセッションに対する完全アクセス権を付与します。

ユーザー ID が完全に一致するセッションへの読み取りアクセス権を付与する

次の条件では、ユーザー ID が userA と完全に一致するセッションに対してのみ、個々の userA@gmail.com に表示アクセス権が付与されます。

つまり、ユーザー ID が userA であれば、セッションを取得してセッションイベントを一覧表示できます。ユーザーは、userB などのユーザー ID を含むセッションにアクセスできません。

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

ユーザー ID に特定の接頭辞が含まれるセッションへの書き込みアクセス権を付与する

次の条件では、user で始まるユーザー ID を含むセッションに対する編集権限が個人 developerA@corp.com に付与されます。接頭辞のチェックには startsWith、接尾辞のチェックには endsWith を使用できます。

つまり、デベロッパーは userA や user1234 などのユーザー ID を使用して、セッションの作成、更新、削除、イベントの追加を行うことができます。

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

2 つのユーザー ID のいずれかを含むセッションに対する完全アクセス権を付与する

次の条件では、グループ group:engineering@corp.com ユーザー（閲覧者と編集者）に、ユーザー ID が userA または user123 のみのセッションへのアクセス権が付与されます。

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

制限事項

プリンシパルの上限: IAM ポリシーは 1,500 個の一意のプリンシパルに制限されます。この上限は、Google グループを使用して管理できます。詳細については、すべてのプリンシパルの上限をご覧ください。
ListSessions API のサポート: ListSessions API は IAM 条件をサポートしていません。ListSessions 権限を付与するには、プリンシパルに aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionUser などの無条件ロール、または関連する無条件の Vertex AI ロールを付与する必要があります。