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

エージェント ID の認証に関する問題のトラブルシューティング

このドキュメントでは、Agent Identity と Agent Identity Auth Manager を使用してエージェントを認証する際に発生する一般的なエラーの解決方法について説明します。

認証プロバイダの構成手順については、Agent Identity 認証プロバイダを管理するをご覧ください。外部サービスで Agent Identity ID トークンを検証する手順については、エージェント自身の ID を使用して外部サービスに対して認証するをご覧ください。

リダイレクト URI の不一致

OAuth フロー中にサードパーティアプリケーションから redirect URI mismatch エラーを受け取った場合は、サードパーティデベロッパーポータルに登録されているリダイレクト URI が、認証マネージャーによって生成された URI と完全に一致していることを確認してください。

この問題を解決するには、 Google Cloud コンソールで認証プロバイダの詳細を表示するか、次の gcloud コマンドを実行して、生成されたリダイレクト URI を確認します。

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

ユーザーロールが割り当てられていない

エージェントが認証プロバイダを使用できない場合は、エージェント ID に認証プロバイダリソースに対する roles/agentidentity.user ロールがあることを確認します。

この問題を解決するには、 Google Cloud コンソールを使用してロールを付与するか、add-iam-policy-binding コマンドを実行します。

発行元エンドポイントに関する問題

OIDC プロバイダの場合は、発行元エンドポイントが一般公開されており、.well-known/openid-configuration ディスカバリドキュメントをサポートしていることを確認します。

Google Cloud が OIDC メタデータまたは JWKS を取得できない場合は、エンドポイントがファイアウォールまたは制限付きネットワークの背後にないことを確認します。

401 UNAUTHENTICATED エラー

エージェントが認証できない場合は、次のエラーが発生することがあります。このエラーは通常、mTLS バインディングと DPoP 暗号証明を適用する Google 管理のコンテキストアウェアアクセスポリシーが原因で発生します。

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

このエラーを解決するには、特定のトークン共有要件がある場合や、ヘッダーにトークンを直接挿入する必要がある場合は、デフォルトのコンテキストアウェアアクセスポリシーをオプトアウトできます。オプトアウトするには、エージェントをデプロイするときに次の環境変数を設定します。

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

API キーサービスがブロックされました（`API_KEY_SERVICE_BLOCKED`）

API キーを検証すると、次のエラーが発生する可能性があります。このエラーは、サービスがブロックされていることを示します。

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

このエラーは、ターゲット API サービス（Cloud Translation API など）が Google Cloud プロジェクトで有効になっていないか、API キーの制限によりこのサービスへのアクセスが許可されていない場合に発生します。

このエラーを解決するには、次の操作を行います。

Google Cloud コンソールで、[API とサービス>ライブラリ] ページに移動し、ターゲット API が有効になっていることを確認します。
[API とサービス] > [ライブラリ] に移動
Google Cloud コンソールで、[API とサービス>認証情報] ページに移動し、API キーを編集して、その API の制限でサービスへのアクセスが許可されていることを確認します。
[API とサービス] > [認証情報] に移動

無効な API キー（`API_KEY_INVALID`）

サードパーティサービスにリクエストを送信すると、次のエラーが発生することがあります。このエラーは、API キーが無効であることを示します。

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

このエラーは、リクエストヘッダーで渡された API キー文字列が正しくないか、形式が正しくないか、プロジェクト認証情報に存在しない場合に発生します。

このエラーを解決するには、 Google Cloud コンソールの [認証情報] ページから正しい API キー文字列をコピーし、先頭または末尾に空白が含まれていないことを確認します。

認証情報の取得が拒否されました（`agentidentity.authProviders.retrieveCredentials`）

adk web をローカルで実行するか、デプロイしたエージェントを操作すると、次の 403 Forbidden エラーが発生することがあります。

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

このエラーは、認証プロバイダの呼び出しを試行しているプリンシパルに、認証情報を取得するために必要な IAM 権限がない場合に発生します。

このエラーを解決するには、プリンシパルに Agent Identity ユーザー（roles/agentidentity.user）ロールを付与します。

ローカル開発（uv run adk web または uvicorn）中にこのエラーが発生した場合は、個人用ユーザーアカウント（user:USER_EMAIL）にロールが付与されていることを確認してください。
デプロイされたエージェントを操作するときにこのエラーが発生した場合は、エージェントの SPIFFE ID プリンシパル（principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID）にロールが付与されていることを確認してください。

一般的なデプロイの失敗

uv run adk deploy を使用してエージェントをデプロイすると、コマンドが失敗し、汎用のエラーメッセージが表示されることがあります。

このエラーは、Python の依存関係の欠落、agent.py の構文エラー、環境変数の構成ミスが原因で発生します。

このエラーを解決するには、次の手順を行います。

Google Cloud コンソールを開き、[ログエクスプローラ] ページに移動します。
一時的なデプロイコンテナのログ（maps_mcp_agent_tmp... や bigquery_mcp_agent_tmp... など）を検索します。
Python のトレースバックを調べて、構文エラーを特定したり、欠落しているパッケージをトレースしたりします。
必要なパッケージがすべて requirements.txt ファイルに記載されていることを確認します。

ServiceNow 認証ループまたは予期しないスコープ

エージェントが 3-legged OAuth を使用して ServiceNow に対して認証を行うと、認証フローが失敗したり、エージェントがリクエストループに入ったりする可能性があります。

この問題は、ServiceNow がエージェントによってリクエストされたスコープではなく、アプリケーションレベルで付与されたスコープを判断するために発生します。管理者が ServiceNow アプリケーションで特定のスコープ（useraccount など）を構成すると、エージェントが別のスコープ（mcp_server など）をリクエストした場合でも、ServiceNow は構成されたスコープのみを含むトークンを返します。エージェントがリクエストされたスコープを厳密に想定または検証する場合、受信したトークンを拒否し、ループで認証情報を再リクエストする可能性があります。

この問題を解決するには、次の操作を行います。

管理者として ServiceNow インスタンスにログインします。
ServiceNow の OAuth アプリケーションの構成に移動します。
エージェントに必要なすべてのスコープが、アプリケーションの許可されたスコープのリストに明示的に追加されていることを確認します。
ServiceNow で有効になっているスコープのみをリクエストするようにエージェントを構成します。

詳細については、サポートされているサードパーティサービスをご覧ください。

GitHub または Microsoft の複数のスコープエラー

GitHub または Microsoft の認証プロバイダを構成するときに、複数の OAuth スコープをリクエストすると、認証が失敗します。

認証マネージャーは、GitHub と Microsoft の単一スコープ統合をサポートしています。認証マネージャーは、複数のスコープの同時リクエストをサポートしていません。

この問題を解決するには、統合に必要な単一のスコープのみをリクエストするようにエージェントまたは認証プロバイダを構成します。

詳細については、サポートされているサードパーティサービスをご覧ください。

OpenID Connect ディスカバリと JWKS エンドポイントのエラー

外部サービスまたは証明書利用者（RP）は、 Google CloudSecurity Token Service OpenID Connect Discovery（/.well-known/openid-configuration）または JSON Web Key Set（/openid/jwks）エンドポイントをクエリして、Agent Identity ID トークンを検証できます。これらのエンドポイントをクエリすると、リクエストが失敗し、HTTP 400、404、429、500 のいずれかのエラーが発生する可能性があります。

次の表に、これらのエラーの原因と解決策を示します。

HTTP ステータス	原因	解決策
`400 Bad Request`	このエラーは、リクエスト URL の Workload Identity プールリソース名が無効であるか、リクエストに `Authorization` HTTP ヘッダーが含まれている場合に発生します。	このエラーを解決するには、次の操作を行います。 Workload Identity プールリソース名が、サポートされているエージェント信頼ドメイン形式（`agents.global.org-ORGANIZATION_ID.system.id.goog` または `agents.global.proj-PROJECT_NUMBER.system.id.goog`）を使用していることを確認します。リクエストから `Authorization` ヘッダーまたは OAuth ヘッダーを削除します。`/.well-known/openid-configuration` エンドポイントと `/openid/jwks` エンドポイントは一般公開されており、認証されていません。認証ヘッダーを渡すと、リクエストは `HTTP 400` エラーで失敗します。
`404 Not Found`	このエラーは、指定された組織 ID、プロジェクト番号、Workload Identity プールが存在しないか、URL パスが正しくない場合に発生します。	このエラーを解決するには、URL の組織 ID、プロジェクト番号、信頼ドメイン（Workload Identity プール ID）が正しいことを確認します。また、URL パスの末尾が `/.well-known/openid-configuration` または `/openid/jwks` であることも確認します。
`429 Too Many Requests`	このエラーは、レスポンスをキャッシュに保存せずに検出エンドポイントまたは JWKS エンドポイントをクエリすることで、検証ツールがリクエストレートの上限を超えた場合に発生します。	このエラーを解決するには、`Cache-Control: public, max-age=86400, must-revalidate` レスポンスヘッダーに従って、検出ドキュメントと JWKS を最大 24 時間キャッシュに保存するように検証ツールを構成します。
`500 Internal Server Error`	このエラーは、公開署名鍵の取得中にサーバーで一時的な内部問題が発生したことが原因で発生します。	このエラーを解決するには、キャッシュに保存された JWKS があればそれを使用するか、指数バックオフでリクエストを再試行します。

鍵のローテーション後にトークン署名の検証が失敗する

外部サービスがAgent Identity ID トークンを検証するときに、同じエージェントの以前のトークンは成功したにもかかわらず、新しく発行されたトークンの署名検証が失敗することがあります。

この問題は、 Google Cloud が Workload Identity プールの秘密署名鍵と公開署名鍵を定期的にローテーションするために発生します。その結果、受信トークンの kid（キー ID）が検証ツールのローカルキーキャッシュに存在しない可能性があります。

この問題を解決するには、認識されない kid を含むトークンを受信したときに、トークンを拒否する前に /openid/jwks エンドポイントから新しい JWKS を取得するように検証ツールを構成します。