AI エージェントを認証する

エージェントを Cloud Run にデプロイするときに、API や他のエージェントと通信するときに安全に認証できる ID をエージェントに付与できます。

Google Cloud API、他のエージェント、ツールに対する認証

Cloud Run ワークロードが agent-identity ID タイプで構成されている場合、次の形式でシステム管理 ID を受け取ります。

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

組織のないプロジェクトの場合、形式ではプロジェクト番号を使用します。

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

この ID を使用して、 Google Cloud API、他のエージェント、ツールと通信するときにエージェントを安全に認証できます。

Google Cloud APIs に対する認証

エージェントは、割り当てられたエージェント ID を使用して、Cloud Run メタデータ サーバーから取得したアクセス トークンを使用して、Vertex AI、Cloud Storage などのGoogle Cloud API やその他のGoogle Cloud プロダクトに対して認証できます。

  1. エージェントのプリンシパルに適切な IAM ロールを付与します。次に例を示します。

    • Vertex AI へのアクセス権を付与する:

      gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"

    • 他の Google Cloud API へのアクセス権を付与する:

      ターゲット リソースに必要なロールを AGENT_PRINCIPAL に付与します。たとえば、Cloud Storage バケットに対する roles/storage.objectViewer などです。詳細については、アプリケーションのデフォルト認証情報で認証するをご覧ください。

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

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • AGENT_PRINCIPAL: エージェントの ID（例: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME）。

  2. エージェント アプリケーション コードで、標準の Google Cloud クライアント ライブラリを使用します。クライアント ライブラリは、アプリケーションのデフォルト認証情報（ADC）を使用して、メタデータ サーバーから有効期間の短いアクセス トークンを自動的に取得します。

    または、コンテナ内のメタデータ サーバーからアクセス トークンを手動で取得することもできます。

    curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"

Cloud Run の他のエージェントに対する認証を行う

エージェントが Cloud Run でホストされている別のエージェント（A2A エージェントなど）を呼び出す必要がある場合は、Cloud Run の組み込み roles/run.invoker IAM チェックによって検証された JSON Web Token（JWT）ID トークンを使用して認証します。

  1. 呼び出し元エージェントの ID に、ターゲットの Cloud Run サービスに対する roles/run.invoker ロールを付与します。

    gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

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

    • TARGET_SERVICE_NAME: 宛先の Cloud Run エージェント サービスの名前。
    • CALLER_AGENT_PRINCIPAL: 呼び出し元エージェントの ID。
    • REGION: ターゲット サービスの Google Cloud リージョン。

トークン検証オプション

Cloud Run は、次の 2 つの ID トークン検証方法をサポートしています。

  • バインドされていないトークン: メタデータ サーバーによって生成される標準のオーディエンス バインド ID トークン。これは、サービス間認証とエージェント間認証のデフォルトのメカニズムです。
  • バウンド トークン: mTLS を使用して、トークンとワークロードの証明書間の暗号バインディングを提供します。バインドされたトークンを使用するには、呼び出し元クライアントがリクエストでリーフ証明書チェーンを提供します。
バインドされていない ID トークンを取得する
  1. 呼び出し元エージェント コンテナ内から、ターゲット サービスの URL をオーディエンスとして ID トークンを取得します。
    TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
     TARGET_SERVICE_URL は、宛先 Cloud Run サービスの URL（例: https://target-agent-1234567890.us-central1.run.app）に置き換えます。
  2. Authorization ヘッダーにトークンを含めて、ターゲット サービスにリクエストを送信します。
    curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint
バインドされた ID トークンを取得する（mTLS）
  1. 呼び出し元エージェント コンテナ内から、リーフ証明書チェーンを読み取り、POST リクエストを使用してメタデータ サーバーからバインド トークンをリクエストします。
    CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")
  2. TLS ハンドシェイク中にワークロード証明書を提示して、ターゲット サービスの mTLS エンドポイントを呼び出します。
    KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint
Python の例

Python ベースのエージェント コードを作成する場合、証明書が存在すると、標準の Google Cloud クライアント ライブラリはデフォルトでバインド トークンを自動的にリクエストします。HTTP リクエストを手動で行う必要がある場合:

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

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

TARGET_SERVICE_MTLS_URL は、宛先 Cloud Run サービスの mTLS URL（例: https://target-agent-12345.us-central1.mtls.run.app）に置き換えます。

Cloud Run の MCP サーバーに対する認証を行う

Cloud Run でホストされている MCP サーバーまたはツールに接続するには、--functional-type=mcp-server 識別子を使用して、Agent Registry での MCP サーバーの自動登録を有効にします。

MCP サーバーに Cloud Run で実行されている他のエージェントのみがアクセスする場合は、組み込みの IAM 起動元チェックを使用します。エージェントが標準の実行呼び出し元ポリシーを使用してネイティブに通信できるようにします。

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

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

  • MCP_SERVICE_NAME: MCP サーバーをホストする宛先 Cloud Run サービスの名前。
  • CALLING_AGENT_PRINCIPAL: MCP サーバーを呼び出すエージェントのプリンシパル ID。例: serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com
  • REGION: MCP サーバーがデプロイされている Google Cloud リージョン。

run.invoker ロールを付与すると、呼び出し元エージェントは、トークン検証オプション セクションで説明されているように、ID トークンを取得できます。

IAP for CLI とプログラム SDK アクセスを使用して MCP サーバーを保護する方法については、MCP サーバーを認証するをご覧ください。

ユーザーに代わって認証する

エージェントがユーザーの代わりに外部ツールやサービスにアクセスする場合、プロビジョニングされたエージェント ID を使用して、MCP サーバーや外部エンドポイントとの認証を管理できます。

3-legged OAuth（3LO）同意、2-legged OAuth（2LO）、API キーなどの複雑な認可ワークフローを安全に処理するには、エージェント ID 認証マネージャーを構成します。

これらの認証マネージャーをツールセットにバインドする手順については、ツールとリソースに対する認証をご覧ください。