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

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

概要

IAM Conditions では、指定された条件が満たされた場合にのみ、セッションとセッション イベントのリソースへのアクセスを許可できます。Common Expression Language で記述された式を含む API 属性 aiplatform.googleapis.com/sessionUserId を使用して、セッション リソース内の 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 つのロールを付与する方法は次のとおりです。

コンソール

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

   [IAM] に移動

2. プロジェクトを選択します。

3. ロールを付与するプリンシパルを選択します。

   • リソースに対する他のロールをすでに持っているプリンシパルにロールを付与するには、プリンシパルを含む行を見つけて、その行で [プリンシパルを編集] をクリックし、[別のロールを追加] をクリックします。

     サービス エージェントにロールを付与するには、[Google提供のロール付与を含みます] チェックボックスをオンにして、メールアドレスを表示します。

     注: リソースへのアクセスを管理するときに、継承されたロールの編集を行うことはできません。継承されたロールを編集するには、ロールが付与されたリソースに移動します。

   • リソースに対する既存のロールを持たないプリンシパルにロールを付与するには、 [アクセスを許可] をクリックし、プリンシパル ID（[e-mail] や //iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail] など）を入力します。

4. 付与するロールをプルダウン リストから選択します。セキュリティのベスト プラクティスに沿って、プリンシパルが必要とする権限のみを含むロールを選択してください。専用のセッション IAM ロールのいずれかを選択できます。

5. API 属性として aiplatform.googleapis.com/sessionUserId を使用して、ロールに条件を追加します。条件ステートメントの例については、下記の例をご覧ください。

6. [保存] をクリックします。リソースのロールがプリンシパルに付与されます。

gcloud

1. 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.

2. add-iam-policy-binding コマンドを使用すると、プリンシパルにロールをすばやく付与できます。

   後述のコマンドデータを使用する前に、次のように置き換えます。

   • PROJECT_ID: 実際の Google Cloud プロジェクト ID。 プロジェクト ID は英数字です（例: my-project）。

   • PRINCIPAL: プリンシパルまたはメンバーの識別子。通常、PRINCIPAL_TYPE:ID の形式で指定します。 例: user:[e-mail] または principalSet://iam.googleapis.com/locations/global/workforcePools/example-pool/group/[e-mail]。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:[e-mail] など）。MEMBER に使用できる値の一覧については、プリンシパル ID をご覧ください。

• CONDITION: API 属性として aiplatform.googleapis.com/sessionUserId を使用する IAM 条件ステートメント。条件ステートメントの例については、下記の例をご覧ください。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

制限事項

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