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

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

エージェントは、独自の ID を使用して Google Cloud API やその他のリソースにアクセスできます。 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）
- Service Usage コンシューマー（roles/serviceusage.serviceUsageConsumer）
- ブラウザ（roles/browser）
- ストレージオブジェクト閲覧者（roles/storage.objectViewer）

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

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

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

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

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

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

コンソール

Google Cloud コンソールで、アクセス権を付与するリソースの [IAM] ページに移動します。
- プロジェクトの場合は、[IAM] ページに移動します。
  [IAM] ページに移動
- 他のリソースの場合は、そのリソースのページに移動し、[権限] タブまたは [IAM] タブをクリックします。
[アクセス権を付与] をクリックします。
[新しいプリンシパル] フィールドに、付与するアクセスレベルに一致するプリンシパル 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/*
[ロールを選択] フィールドで、付与するロールを検索して選択します。
[保存] をクリックします。

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 環境にデプロイされると、自動的にエージェント ID を使用します。

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

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 が管理するデフォルトのコンテキストアウェアアクセスポリシーは、エージェント ID 認証情報の保護に役立ちます。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 トークン: 外部サービス、および Google Cloud ランタイムでホストされているツールとサービス（Cloud Run（*.mtls.run.app）や GKE など）へのリクエストを認証する JSON Web Token（JWT）。

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

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

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

エージェント間でトークンを共有するための特定の要件がある。
トークンをリクエストヘッダーに直接挿入する必要があります。
エージェントが認証できず、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にデプロイするときに、エージェント ID が有効になっていることを確認します。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]"],
    },
)