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

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

Agent Identity と Agent Identity Auth Manager を使用してエージェントを認証する際の一般的なエラーを解決するには、認証プロバイダの構成、Identity and Access Management（IAM）ロールバインディング、OAuth スコープ、OpenID Connect（OIDC）トークン検証の設定を確認します。

認証プロバイダを管理するには、Agent Identity 認証プロバイダを管理するをご覧ください。外部サービスでエージェント ID の 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 User（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）エンドポイントにクエリを実行して、エージェント 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 を使用するか（使用可能な場合）、指数バックオフを使用してリクエストを再試行します。

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

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

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

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