Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

エージェント独自の ID を使用して Google Cloud に対して認証する

エージェントは、独自の ID を使用して Google Cloud API やその他のリソースにアクセスできます。Google は、 Google Cloud でホストされているエージェントが他の Google Cloud サービスとやり取りする場合に、この方法を使用することをおすすめします。

エージェントが独自の権限で動作する場合、プライマリ SPIFFE ID を使用して Google Cloud アクセストークンをリクエストします。

始める前に

正しい認証方法を選択していることを確認します。
Agent Identity を有効にしてエージェントを作成し、デプロイします。
このタスクを完了するために必要なロールが付与されていることを確認します。

必要なロール

エージェントにサービスへのアクセス権を付与するために必要な権限を取得するには、 Google Cloud サービスにターゲットリソースに対して次の IAM ロールを付与するよう管理者に依頼してください。

エージェントにアクセス権を付与するには:
- プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
- セキュリティ管理者（roles/iam.securityAdmin）
エージェント ID に推奨されるロール:
- エージェントコンテキスト編集者（roles/aiplatform.agentContextEditor）
- エージェントのデフォルトアクセス（roles/aiplatform.agentDefaultAccess）
- Vertex AI ユーザー（roles/aiplatform.user）
- Service Usage コンシューマー（roles/serviceusage.serviceUsageConsumer）
- ブラウザ（roles/browser）
- ストレージオブジェクト閲覧者（roles/storage.objectViewer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

エージェントにアクセス権を付与する

エージェントが Google Cloud サービスにアクセスできるようにするには、ターゲットリソースに必要なロールをエージェントの ID に付与する必要があります。

IAM 許可ポリシーでは、エージェント ID は プリンシパル IDを使用します。

エージェントにリソースへのアクセス権を付与するには、 Google Cloud コンソールまたは gcloud CLI を使用します。

Console

Google Cloud コンソールで、アクセス権を付与するリソースの [IAM] ページに移動します。
- プロジェクトの場合は、[IAM] ページに移動します。
  [IAM] ページに移動
- その他のリソースの場合は、そのリソースのページに移動し、 [権限] タブまたは [IAM] タブをクリックします。
[ [Grant Access]] をクリックします。
[**新しいプリンシパル**] フィールドに、付与するアクセスレベルに一致するプリンシパル ID を入力します。
- 単一のエージェント: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- プロジェクト内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- 組織内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
In the [**Select a role**] field, search for and select the role that you want to grant.
[保存] をクリックします。

Google Cloud CLI

エージェントにリソースへのアクセス権を付与するには、次のコマンドを実行します。

gcloud SERVICE add-iam-policy-binding RESOURCE_NAME \
    --member="PRINCIPAL_IDENTIFIER" \
    --role="ROLE"

次のように置き換えます。

SERVICE： Google Cloud サービス（例： storage または bigquery）。
RESOURCE_NAME: リソースの名前（たとえば、バケット名やデータセット ID など）。
PRINCIPAL_IDENTIFIER: 付与するアクセスレベルに一致するプリンシパル ID。
- 単一のエージェント: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
- プロジェクト内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
- 組織内のすべてのエージェント: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*
ORGANIZATION_ID: Google Cloud 組織 ID。
PROJECT_NUMBER: あなたの Google Cloud プロジェクトの番号。
LOCATION: エージェントのロケーション（ us-central1 など）。（単一エージェントアクセスの場合にのみ必要）
ENGINE_ID: 推論エンジンの ID。（単一エージェントアクセスの場合にのみ必要）
ROLE: 付与する IAM ロール。

コードでエージェント ID を参照する

Google Cloud エージェントがサポートされている Google Cloud 環境にデプロイされると、クライアントライブラリは自動的に Agent Identity を使用します。

次の Python スニペットは、Agent Development Kit（ADK）を使用して Agent Identity 認証情報を手動で使用して Cloud Vision API を呼び出す方法を示しています。

from google.cloud import vision
from google.auth import default
from google.adk.tools import tool

@tool
def analyze_image_from_gcs(gcs_uri: str) -> dict:
    # Application default credentials automatically retrieve the
    # Agent Identity token from the metadata server.
    agent_identity_credentials, project_id = default()

    client = vision.ImageAnnotatorClient(
        credentials=agent_identity_credentials,
        project=project_id
    )

    # Prepare the image object with the Cloud Storage URI.
    image = vision.Image()
    image.source.image_uri = gcs_uri

    # Perform label detection on the image.
    response = client.label_detection(image=image)

    # Check for any errors returned by the API.
    if response.error.message:
        return {"status": "failure", "error_message": response.error.message}

    labels = response.label_annotations
    return {"status": "success", "labels": [label.description for label in labels]}

省略可: 証明書バインドトークンをオプトアウトする

デフォルトの Google マネージドコンテキストアウェアアクセスポリシーは、Agent Identity 認証情報の保護に役立ちます。Agent Gateway を超えて、ポリシーはエージェントのアクセストークンを認証することで、Demonstrating Proof of Possession（DPoP）を適用します。また、このポリシーでは、Agent Gateway にアクセスするために相互 TLS（mTLS）が必要です。この要件により、Cloud Run コンテナや Google Kubernetes Engine（GKE）Pod などの意図した信頼できるランタイム環境のみが、証明書バインドトークンを使用できるようになります。このセキュリティベースラインにより、盗まれた認証情報を再利用できなくなり、認証情報の盗難やアカウントの乗っ取り（ATO）を防ぐことができます。

証明書のバインディングは、次の 2 種類のエージェント認証情報の保護に役立ちます。

Google Cloud アクセストークン: Google Cloud API やその他のリソース（*.googleapis.com）へのリクエストを認証する有効期間の短い OAuth 2.0 アクセストークン。
OpenID Connect（OIDC）ID トークン: 外部サービス、および Cloud Run（*.mtls.run.app）や GKE などの Google Cloud ランタイムでホストされているツールやサービスへのリクエストを認証する JSON ウェブトークン（JWT）。

すべてのアクセストークンと ID トークンのバインディングをオプトアウトする

ランタイム環境全体でデフォルトのコンテキストアウェアアクセスポリシーと証明書バインドトークンをオプトアウトすることはおすすめしません。 GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false を設定すると、トークンバインディング保護が削除され、アクセストークンと OIDC ID トークンの両方 Google Cloud がこれらの有効期間の短いトークンを盗難やリプレイ攻撃に対して脆弱にします。

ただし、次のようなまれなケースでは、ランタイム環境全体でオプトアウトできます。

エージェント間でトークンを共有するための特定の要件がある。
トークンをリクエストヘッダーに直接挿入する必要がある。
エージェントが認証できず、401 UNAUTHENTICATED エラーが返される。

ランタイム環境全体でオプトアウトするには、エージェントをデプロイするときに次の環境変数を設定します。

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

個々の ID トークンリクエストをオプトアウトする

デフォルトでは、サポートされている Google Auth クライアントライブラリは、トークンの cnf（x5t#S256）クレームに証明書のフィンガープリントを含めることで、OIDC ID トークンをエージェントの一意の X.509 証明書に暗号的にバインドします。

Cloud Run などの一部のサービスでは、cnf クレームが存在する場合に証明書のバインディングが適用されます。エージェントが標準の *.run.app URL などの非 mTLS エンドポイントを介してこれらのサービスを呼び出す場合、またはターゲットエンドポイントで証明書のバインディングが不要な場合は、個々の ID トークンリクエストをオプトアウトできます。この設定はリクエストにのみ影響し、アクセストークンの証明書バインディング Google Cloud は無効になりません。

Python

Python google-auth ライブラリ（GKE では 2.61.0 以降、Cloud Run では 2.62.0 以降）で、bind_id_token=False を設定します。

from google.auth.transport.requests import AuthorizedSession
from google.auth.transport.requests import Request
from google.oauth2 import id_token

target_audience = "https://TARGET_SERVICE_URL"

# Option 1: Use AuthorizedSession with IDTokenCredentials
credentials = id_token.fetch_id_token_credentials(
    audience=target_audience,
    bind_id_token=False,
)
authed_session = AuthorizedSession(credentials)
response = authed_session.get(target_audience)

# Option 2: Fetch a raw ID token directly
token = id_token.fetch_id_token(
    Request(),
    audience=target_audience,
    bind_id_token=False,
)

TARGET_SERVICE_URL は、エージェントが呼び出す受信サービスのオーディエンス URI または URL に置き換えます。

エージェントをデプロイする

エージェントを Google Cloudにデプロイする場合は、Agent Identity が有効になっていることを確認してください。 Gemini Enterprise Agent Platform の Agent Runtime にデプロイする場合は、identity_type=AGENT_IDENTITY フラグを使用します。

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)