デフォルトでは、セッションの Identity and Access Management 権限はプロジェクト レベルです。このドキュメントでは、IAM 条件を使用して Agent Platform Sessions リソースへのアクセスをより詳細に制御する方法について説明します。
概要
IAM Conditions では、指定された条件が満たされた場合にのみ、セッション リソースとセッション イベント リソースへのアクセスを許可できます。セッションへのアクセスは、API 属性 aiplatform.googleapis.com/sessionUserId と Common Expression Language で記述された式を使用して、Session リソース内の userId 文字列に基づいて制御できます。ユーザー ID は、セッションの作成時に指定される任意の文字列です(例: userId = "userA")。
これらの条件付き Identity and Access Management ポリシーはプロジェクト レベルで作成され、プロジェクト内のすべてのセッションとセッション イベントに適用されます。IAM 条件は、プロジェクトのユーザーやサービス アカウントなど、あらゆる種類のプリンシパルに適用できます。
IAM 条件は、Identity and Access Management(IAM)権限を、まだ存在しないリソースを含む多くの関連セッション リソースに同時に付与する場合に役立ちます。セッションとイベントへのアクセスを制限して、ユーザーが自分の情報にのみアクセスできるようにしたり、デベロッパーが特別な権限を付与されることなく特定のセッション リソースのみを表示できるようにしたりできます。
始める前に
セッションとセッション イベントに条件付き Identity and Access Management ポリシーを設定するには、次の操作を行います。
- IAM 条件を確認する: IAM 条件の概要を理解します。
- 必要なロールを決定する: 最小権限の原則を遵守するために、ユースケースに適した特殊なセッション IAM ロールを特定します。
-
影響を受けるプリンシパルを特定する: 組織内の誰にどの権限を付与する必要があるかを特定します。たとえば、次の点を考慮します。
- ユーザーが別のユーザーのセッションを表示できるようにする必要があるか。
- デベロッパーはすべてのセッションを表示できる必要がありますか?
- プロジェクト管理者がすべてのセッションを表示できるようにする必要があるか。
- 特定のエージェント ID が特定のセッションにアクセスできるようにする必要があるか。
-
IAM ロールを付与する: このドキュメントのタスクを実行するために必要な権限を含むロールが付与されていることを確認します。
Agent Platform Sessions リソースに IAM 条件を適用するために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。
- プロジェクトの場合: プロジェクト IAM 管理者(`roles/resourcemanager.projectIamAdmin`)
ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
これらの事前定義ロールには、Agent Platform Sessions リソースに IAM 条件を適用するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
IAM 条件を Agent Platform Sessions リソースに適用するには、次の権限が必要です。
- プロジェクト レベルで条件付き IAM アクセス権を設定します。 `resourcemanager.projects.setIamPolicy`
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
組織全体で IAM Conditions を使用する場合は、組織のポリシーを管理する権限も必要です。
セッションの条件付きアクセスの作成
プロジェクト レベルで Identity and Access Management ポリシー バインディングに条件を追加して、セッションへの条件付きアクセスを許可します。この条件では、api.getAttribute('aiplatform.googleapis.com/sessionUserId', "") 関数を使用してセッション リソースのユーザー ID を検査します。ユーザー ID は、セッションを作成するときに定義します。
条件付きの IAM ポリシーの作成に関する詳細なガイドについては、許可ポリシーの条件をご覧ください。
プリンシパルに 1 つのロールを付与する方法は次のとおりです。
コンソール
Google Cloud コンソールで、[IAM] ページに移動します。
プロジェクトを選択します。
ロールを付与するプリンシパルを選択します。
リソースに対する他のロールをすでに持っているプリンシパルにロールを付与するには、プリンシパルを含む行を見つけて、その行で [ プリンシパルを編集] をクリックし、[ 別のロールを追加] をクリックします。
サービス エージェントにロールを付与するには、[ Google提供のロール付与を含みます] チェックボックスをオンにして、メールアドレスを表示します。
リソースに対する既存のロールを持たないプリンシパルにロールを付与するには、 [アクセスを許可] をクリックし、プリンシパル ID を入力します。たとえば、
my-user@example.comや//iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.comです。
付与するロールをプルダウン リストから選択します。セキュリティのベスト プラクティスに沿って、プリンシパルが必要とする権限のみを含むロールを選択してください。専用の Session IAM ロールのいずれかを選択できます。
aiplatform.googleapis.com/sessionUserIdを API 属性として使用して、ロールに条件を追加します。条件ステートメントの例については、以下の例をご覧ください。[保存] をクリックします。リソースのロールがプリンシパルに付与されます。
gcloud
-
Google Cloud コンソールで 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:aiplatform.googleapis.com/sessionUserIdを API 属性として使用して、ロールに条件を追加します。条件ステートメントの例については、以下の例をご覧ください。
次のコマンドを実行します。
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:aiplatform.googleapis.com/sessionUserIdを API 属性として使用する 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 条件を使用する場合は、過剰な権限を付与する IAM ポリシーの設定を阻止することが重要です。次の表に、セッション API に条件付き IAM ロールを付与するときに使用できる特殊なロールを示します。
| ロール名 | 説明 | 含まれる権限 |
|---|---|---|
roles/aiplatform.sessionViewer |
セッションとリスティング イベントに対する読み取り専用権限を付与します。 |
|
roles/aiplatform.sessionEditor |
セッションへの書き込みアクセス権とイベントの追加権限を付与します。 |
|
roles/aiplatform.sessionUser |
セッションとイベントに対する完全アクセス権(すべての閲覧者権限と編集者権限を含む)を付与します。 |
sessionEditor と sessionViewer の両方のすべての権限が含まれます。 |
セッションでの IAM 条件 の使用
このセクションでは、セッションで IAM 条件 を使用する次の例について説明します。
ユーザー 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 グループを使用して管理できます。詳細については、すべてのプリンシパルの上限をご覧ください。
ListSessionsAPI のサポート: ListSessions API は IAM 条件をサポートしていません。ListSessions 権限を付与するには、aiplatform.googleapis.com/sessionViewer、aiplatform.googleapis.com/sessionUser、または関連する無条件の Gemini Enterprise Agent Platform ロールなど、無条件のロールをプリンシパルに付与する必要があります。