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

エージェント自身の ID を使用して外部サービスに対して認証する

Google Cloud でホストされているエージェントは、Agent Identity から OpenID Connect（OIDC）ID トークンをリクエストすることで、独自の ID を使用して、Cloud Run や Google Kubernetes Engine（GKE）などの Google Cloud ランタイムでホストされているツールやサービスに対して認証できます。エージェントは、これらの ID トークンを使用して、サードパーティのクラウドプラットフォーム（Amazon Web Services（AWS）、Microsoft Azure など）、カスタム API、API ゲートウェイ、オンプレミスバックエンドに対する認証を行うこともできます。

エージェントが独自の権限で外部サービスにアクセスすると、エージェント ID は OpenID Connect（OIDC）ID トークンを発行します。この JSON Web Token（JWT）は、エージェントの SPIFFE ID をアサートし、エージェントの信頼ドメイン（マネージドワークロード ID プール）の発行者鍵によって署名されます。外部システムは、 Google Cloud Security Token Service によってホストされるパブリックエンドポイントを介して、認証情報や SDK なしでこれらのトークンを検証できます。 Google Cloud

OpenID プロバイダメタデータと公開鍵エンドポイント（jwks_uri）を公開する OpenID Connect Discovery 1.0 エンドポイント（/.well-known/openid-configuration）。
エージェント ID トークンの署名の検証に使用されるアクティブな公開鍵を提供する JSON Web Key Set（JWKS）エンドポイント（/openid/jwks）。

始める前に

正しい認証方法を選択していることを確認します。Agent Identity の概要で、SPIFFE ID、信頼ドメイン、エージェント認証情報の仕組みを確認します。
Agent Identity を有効にしてエージェントを作成してデプロイします。
外部サービスまたは ID プロバイダが次の要件を満たしていることを確認します。
- OpenID Connect Discovery 1.0 と JSON Web Key Set（JWKS）を使用した JSON Web Token（JWT）の検証をサポートします。
- https://sts.googleapis.com にアウトバウンド HTTPS リクエストを送信して、OpenID プロバイダのメタデータと公開署名鍵を取得できます。
エージェントとターゲットの外部サービスの次の構成値を特定します。
- 発行元 URL（iss クレーム）: 組織（https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN）またはプロジェクト（https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN）の Workload Identity プール発行元 URL。
- 許可されたオーディエンス（aud クレーム）: 外部サービスまたは ID プロバイダが ID トークンを検証するときに想定するオーディエンス URI。
このタスクを完了するために必要なロールが付与されていることを確認します。

必要なロール

Agent Identity を使用してエージェントをデプロイするために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

Gemini Enterprise Agent Platform のエージェントランタイムにエージェントをデプロイする: Vertex AI ユーザー（roles/aiplatform.user）
エージェントサービスを Cloud Run にデプロイする: Cloud Run 管理者（roles/run.admin）

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

これらの事前定義ロールには、Agent Identity を使用してエージェントをデプロイするために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

Agent Identity を使用してエージェントをデプロイするには、次の権限が必要です。

Gemini Enterprise Agent Platform の Agent Runtime にエージェントをデプロイします。
- aiplatform.reasoningEngines.create
- aiplatform.reasoningEngines.update
エージェントサービスを Cloud Run にデプロイします。
- run.services.create
- run.services.update

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

エージェントの OIDC ID トークンを取得する

OIDC ID トークンを取得して外部サービスに送信するようにエージェントを構成するには、次の操作を行います。

Agent Identity を使用してエージェントを構成する
アプリケーションコードで OIDC ID トークンをリクエストする

Agent Identity を使用してエージェントを構成する

エージェントをデプロイするときに Agent Identity を有効にします。

Gemini Enterprise Agent Platform の Agent Runtime にエージェントをデプロイする場合は、identity_type を AGENT_IDENTITY に設定します。

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

コンテナ化されたエージェントサービスを Cloud Run にデプロイする場合は、--identity-type=agent-identity フラグを渡します。
```
gcloud run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --identity-type=agent-identity \
    --no-allow-unauthenticated
```
次のように置き換えます。
- SERVICE_NAME: Cloud Run サービスの名前。
- IMAGE_URL: エージェントのコンテナイメージ URL。

アプリケーションコードで OIDC ID トークンをリクエストする

エージェントのアプリケーションコードで、Google Auth クライアントライブラリを使用して、ターゲットの外部ユーザー向けの OIDC ID トークンをリクエストします。クライアントライブラリは、メタデータサーバーからのトークン生成、ローカルキャッシュ保存、自動更新を処理します。

デフォルトでは、外部オーディエンスに対して発行された OIDC ID トークンは、ランタイム証明書にバインドされません。

次の例では、google-auth ライブラリを使用して OIDC ID トークンをリクエストし、送信リクエストの Bearer トークンとして付加しています。

Python

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

# 1. Specify the audience expected by the external receiver
# (for example, AWS Bedrock AgentCore or your external service URL).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create ID token credentials and an AuthorizedSession, which handles
# local token caching, automatic renewal before expiry, and the Bearer header.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)

# 3. Send the authenticated request to the external service.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

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

EXTERNAL_SERVICE_AUDIENCE: 受信サービスが想定するオーディエンス URI（bedrock.us-east-1.amazonaws.com や api.example.com など）。
EXTERNAL_SERVICE_ENDPOINT: エージェントが呼び出す外部 API またはバックエンドエンドポイントの URL。

他のプログラミング言語（Go、Node.js、Java など）のクライアントライブラリの手順と例については、ID トークンを取得するをご覧ください。これらの言語の現在のクライアントライブラリバージョンは --identity-type=agent-identity をサポートしていますが、デフォルトではバインドされたトークンを使用しません。

Agent Identity の ID トークンを検証する

外部サービスがエージェントから OIDC ID トークンを受け取った場合は、ターゲットサービスに基づいて次のいずれかの方法でトークンを検証します。

マネージドクラウドプラットフォーム（Cloud Run、AWS、Microsoft Azure など）: 組み込みの Workload Identity 連携を使用して、カスタム確認コードを記述せずに受信トークンを検証します。
カスタムバックエンドサービス、API ゲートウェイ、オンプレミスワークロード: 公開 OpenID Connect Discovery エンドポイントと JWKS エンドポイントを使用して、トークンをプログラムで検証します。

組み込みの Workload Identity 連携を使用する

受信サービスが、組み込みの IAM 認証または OIDC ワークロード ID 連携をサポートするクラウドプラットフォームで実行されている場合は、カスタムトークン検証コードを作成する必要はありません。

Cloud Run: 受信サービスが認証済み上り（内向き）（--no-allow-unauthenticated）で Cloud Run で実行されている場合、Cloud Run は上り（内向き）レイヤで受信 Agent Identity トークンを検証します。受信側のサービスで、呼び出し元エージェントに Cloud Run 起動元（roles/run.invoker）ロールを付与します。詳細については、Cloud Run の MCP サーバーに対して認証するをご覧ください。

サービスで認証されていない上り（内向き）が許可され、アプリケーションコードでトークンが検証される場合は、トークンをプログラムで検証するをご覧ください。
Amazon Bedrock:Google Cloud Security Token Service 検出 URL または発行者 URL と想定されるオーディエンスを指定して、インバウンド JWT 認証を構成します。手順については、AWS ドキュメントのインバウンド JWT 認可ツールを構成するをご覧ください。
Microsoft Entra ID: その他の発行元シナリオで連携 ID 認証情報を構成します。 Google Cloud Security Token Service の発行元 URL、想定されるオーディエンス、サブジェクト識別子（sub クレーム）を指定します。手順については、Microsoft Learn ドキュメントのアプリと外部 ID プロバイダ間の信頼関係を作成するをご覧ください。

プログラムでトークンを検証する

エージェントがカスタム API、マイクロサービス、API ゲートウェイ、オンプレミスワークロードにリクエストを送信する場合、受信サービスはアクセスを許可する前に、受信した OIDC ID トークンを検証する必要があります。通常、エージェントはこのトークンを Authorization: Bearer TOKEN HTTP ヘッダーで渡します。

受信した ID トークンをプログラムで検証するには、次の操作を行います。

トークン発行元の URL を抽出して検証する
署名用の公開鍵を検出してキャッシュに保存する
トークンの署名とクレームを検証する
エージェントの SPIFFE ID を承認する

トークン発行者の URL を抽出して検証する

受信リクエストが届いたら、未検証の JWT ペイロードを読み取って iss（発行者）クレームを抽出します。このクレームには、エージェントの信頼ドメインの Workload Identity プールの URL が含まれています。この URL は、ディスカバリドキュメントと公開署名鍵のベース URL として機能します。

アウトバウンドネットワークリクエストを行う前に、iss クレームが組織またはプロジェクトの想定される Google Cloud Security Token Service Workload Identity プール URL と一致することを確認します。

組織レベルの信頼ドメイン:
```
https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN
```
たとえば、ID が 123456789012 の組織の場合、TRUST_DOMAIN は agents.global.org-123456789012.system.id.goog です。
プロジェクトレベルの信頼ドメイン（組織のないプロジェクトの場合）:
```
https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN
```
たとえば、番号が 9876543210 のプロジェクトの場合、TRUST_DOMAIN は agents.global.proj-9876543210.system.id.goog です。

公開署名鍵を検出してキャッシュに保存する

発行者の URL を検証したら、 Google Cloud セキュリティトークンサービスから公開署名鍵を取得してキャッシュに保存します。

OpenID Connect ディスカバリエンドポイントをクエリする: ベース発行元 URL に /.well-known/openid-configuration を追加し、認証されていない HTTP GET リクエストを送信します。

リクエストのデータを使用する前に、次のように置き換えます。

ORGANIZATION_ID: Google Cloud組織 ID。組織のないプロジェクトの場合は、organizations/ORGANIZATION_ID を projects/PROJECT_NUMBER に置き換えます。
TRUST_DOMAIN: エージェントの信頼ドメインの Workload Identity プール ID（例: agents.global.org-123456789012.system.id.goog）。

HTTP メソッドと URL:

GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。

curl -X GET \
     "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration"

PowerShell（Windows）

次のコマンドを実行します。

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration" | Select-Object -Expand Content

リクエストが成功すると、HTTP 200 OK ステータスと、jwks_uri フィールドを含む OpenID プロバイダメタデータを含む JSON オブジェクトが返されます。

{
  "issuer": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog",
  "jwks_uri": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/openid/jwks",
  "authorization_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/authorize",
  "token_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/token",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

JSON Web Key Set（JWKS）エンドポイントをクエリする: OpenID プロバイダメタデータで返された jwks_uri URL に、認証されていない HTTP GET リクエストを送信します。

リクエストのデータを使用する前に、次のように置き換えます。
- ORGANIZATION_ID: Google Cloud組織 ID。組織のないプロジェクトの場合は、organizations/ORGANIZATION_ID を projects/PROJECT_NUMBER に置き換えます。
- TRUST_DOMAIN: エージェントの信頼ドメインの Workload Identity プール ID（例: agents.global.org-123456789012.system.id.goog）。
HTTP メソッドと URL:
```
GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks
```
リクエストを送信するには、次のいずれかのオプションを展開します。
curl（Linux、macOS、Cloud Shell）

次のコマンドを実行します。
```
curl -X GET \
     "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks"
```
PowerShell（Windows）

次のコマンドを実行します。
```
$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks" | Select-Object -Expand Content
```
リクエストが成功すると、HTTP 200 OK ステータスと、RFC 7517 に従ってフォーマットされた公開鍵の配列を含む JSON オブジェクトが返されます。
```
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "4d1933f8e6c4e0b512c140989f6655c68997...",
      "n": "uQn4zN_1mQ0VpGv82-Wp3w...",
      "e": "AQAB"
    }
  ]
}
```
ディスカバリドキュメントと鍵をキャッシュに保存する: OpenID Connect ディスカバリエンドポイントと JWKS エンドポイントの両方からのレスポンスには、次の HTTP キャッシュヘッダーが含まれています。
```
Cache-Control: public, max-age=86400, must-revalidate
```
ディスカバリドキュメントと JWKS を最大 24 時間（86400 秒）キャッシュに保存して、検証のパフォーマンスを向上させ、レート制限を回避します。

Google Cloud は、Workload Identity プールの秘密署名鍵と公開署名鍵を定期的にローテーションします。検証ツールがローカル鍵キャッシュにない kid（鍵 ID）を含む受信トークンを受け取った場合は、トークンを拒否する前に /openid/jwks エンドポイントから新しい JWKS を取得します。

検出エンドポイントまたは JWKS エンドポイントのクエリ時に HTTP エラーが発生した場合は、Agent Identity 認証の問題のトラブルシューティングをご覧ください。

トークンの署名とクレームを検証する

トークンの署名を暗号的に検証し、JWT クレームを検証するには、標準の OIDC または JWT 検証ライブラリ（Google Tink など）を使用して、次の操作を行います。

署名: JWT ヘッダーの kid（鍵 ID）と一致する公開鍵を、キャッシュに保存された JWKS から見つけます。alg フィールド（RS256）で指定されたアルゴリズムを使用して署名を検証します。前方互換性を確保するため、アルゴリズムタイプをハードコードするのではなく、JWKS の alg フィールドと kty フィールドを動的に検査します。
発行者（iss）: iss クレームが、信頼ドメインの信頼できるGoogle Cloud Workload Identity プール発行者 URL と一致していることを確認します。
オーディエンス（aud）: aud クレームがサービスの構成済みオーディエンス識別子と一致していることを確認します。
発行時刻（iat）と有効期限（exp）: iat クレームが過去のものであり、現在の時刻が exp クレームよりも前であることを確認します（1 ～ 2 分程度の小さなクロックスキュー許容範囲を認めます）。

次の例では、Google Tink（tink.jwt）を使用して、JWKS JSON ペイロードに対して Agent Identity ID トークンを検証します。

Python

import tink
from tink import jwt

# Initialize Tink JWT signature primitives (call once at application startup).
jwt.register_jwt_signature()


def verify_agent_identity_token(
    token: str,
    jwks_json: str,
    expected_issuer: str,
    expected_audience: str,
) -> jwt.VerifiedJwt:
    """Verifies an Agent Identity JWT against a JWKS JSON string using Tink.

    Args:
        token: The compact serialized JWT string.
        jwks_json: The JWKS JSON string fetched from the STS pool endpoint.
        expected_issuer: The expected token issuer ('iss' claim).
        expected_audience: The expected token audience ('aud' claim).

    Returns:
        jwt.VerifiedJwt: The verified JWT claims object.

    Raises:
        tink.TinkError: If the JWKS cannot be parsed, the key is not found,
            or token validation (signature, issuer, audience, expiration) fails.
    """
    # 1. Convert the JWKS JSON into a Tink public KeysetHandle.
    keyset_handle = jwt.jwk_set_to_public_keyset_handle(jwks_json)

    # 2. Instantiate the Tink JwtPublicKeyVerify primitive.
    jwt_verifier = keyset_handle.primitive(jwt.JwtPublicKeyVerify)

    # 3. Configure expected validation rules (issuer, audience, expiration).
    # Google Cloud STS sets 'typ': 'JWT' in the header, so
    # expected_type_header="JWT" is required.
    validator = jwt.new_validator(
        expected_issuer=expected_issuer,
        expected_audience=expected_audience,
        expected_type_header="JWT",
        allow_missing_expiration=False,
    )

    # 4. Cryptographically verify the signature and standard OIDC claims.
    return jwt_verifier.verify_and_decode(token, validator)

エージェントの SPIFFE ID を承認する

トークンの署名と標準クレームを確認したら、確認済みの sub（サブジェクト）クレームを調べてリクエストを承認し、呼び出し元エージェントを監査ログに記録します。

sub クレームには、エージェントの一意の SPIFFE ID が含まれています。例:

  spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent

サービスの認可ロジックで、保護されたリソースへのアクセスを許可する前に、検証済みの sub クレームを信頼できるエージェントの SPIFFE ID（または信頼ドメインの接頭辞）の許可リストと比較します。

エージェント自身の ID を使用して外部サービスに対して認証する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

必要なロール

必要な権限

エージェントの OIDC ID トークンを取得する

Agent Identity を使用してエージェントを構成する

アプリケーション コードで OIDC ID トークンをリクエストする

Python

Agent Identity の ID トークンを検証する

組み込みの Workload Identity 連携を使用する

プログラムでトークンを検証する

トークン発行者の URL を抽出して検証する

公開署名鍵を検出してキャッシュに保存する

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

トークンの署名とクレームを検証する

Python

エージェントの SPIFFE ID を承認する

次のステップ

エージェント自身の ID を使用して外部サービスに対して認証する

アプリケーションコードで OIDC ID トークンをリクエストする