Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Résoudre les problèmes d'authentification de l'identité de l'agent

Pour résoudre les erreurs courantes lors de l'authentification des agents avec Agent Identity et le gestionnaire d'authentification Agent Identity, vérifiez les configurations de votre fournisseur d'authentification, les liaisons de rôles Identity and Access Management (IAM), les champs d'application OAuth et les paramètres de validation des jetons OpenID Connect (OIDC).

Pour gérer les fournisseurs d'authentification, consultez Gérer les fournisseurs d'authentification Agent Identity. Pour vérifier les jetons d'ID d'identité de l'agent dans des services externes, consultez S'authentifier auprès de services externes à l'aide de l'identité d'un agent.

Incohérence de l'URI de redirection

Si vous recevez une erreur redirect URI mismatch de l'application tierce pendant le flux OAuth, assurez-vous que l'URI de redirection enregistré dans le portail des développeurs tiers correspond exactement à l'URI généré par le gestionnaire d'authentification.

Pour résoudre ce problème, recherchez l'URI de redirection généré en affichant les détails du fournisseur d'authentification dans la console Google Cloud ou en exécutant la commande gcloud suivante :

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

Rôle utilisateur manquant

Si votre agent ne peut pas utiliser le fournisseur d'authentification, vérifiez que l'identité de l'agent dispose du rôle roles/agentidentity.user sur la ressource du fournisseur d'authentification.

Pour résoudre ce problème, attribuez le rôle à l'aide de la console Google Cloud ou exécutez la commande add-iam-policy-binding.

Problèmes liés au point de terminaison de l'émetteur

Pour les fournisseurs OIDC, vérifiez que le point de terminaison de l'émetteur est accessible publiquement et qu'il est compatible avec le document de découverte .well-known/openid-configuration.

Si Google Cloud ne peut pas récupérer les métadonnées OIDC ou JWKS, assurez-vous que le point de terminaison ne se trouve pas derrière un pare-feu ou un réseau restreint.

Erreur 401 UNAUTHENTICATED

Si votre agent ne peut pas s'authentifier, l'erreur suivante peut se produire. Cette erreur est généralement due à une règle d'accès contextuel gérée par Google qui applique la liaison mTLS et les preuves cryptographiques DPoP :

{
  "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"
  }
}

Pour résoudre cette erreur, vous pouvez désactiver la règle d'accès contextuel par défaut lorsque vous avez des exigences spécifiques de partage de jetons ou que vous devez injecter le jeton directement dans l'en-tête. Pour désactiver cette option, définissez la variable d'environnement suivante lorsque vous déployez votre agent :

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

Service de clé API bloqué (`API_KEY_SERVICE_BLOCKED`)

Si vous validez votre clé API, l'erreur suivante peut se produire. Cette erreur indique que le service est bloqué :

"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."
  }
]

Cette erreur se produit, car le service d'API cible (par exemple, l'API Cloud Translation) n'a pas été activé dans votre projet Google Cloud , ou les restrictions de la clé API n'autorisent pas l'accès à ce service.

Pour résoudre cette erreur, procédez comme suit :

Dans la console Google Cloud , accédez à la page API et services > Bibliothèque et vérifiez que l'API cible est activée.
Accédez à API et services > Bibliothèque.
Dans la console Google Cloud , accédez à la page API et services >Identifiants, modifiez votre clé API et vérifiez que ses restrictions d'API autorisent l'accès au service.
Accédez à API et services > Identifiants.

Clé API non valide (`API_KEY_INVALID`)

Lorsque vous envoyez des requêtes à un service tiers, l'erreur suivante peut se produire. Cette erreur indique que la clé API n'est pas valide :

"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."
  }
]

Cette erreur se produit, car la chaîne de clé API transmise dans l'en-tête de requête est incorrecte, malformée ou n'existe pas dans les identifiants de votre projet.

Pour résoudre cette erreur, vérifiez que vous avez copié la bonne chaîne de clé API depuis la page Identifiants de la console Google Cloud et que vous n'avez pas inclus d'espace au début ou à la fin.

Autorisation refusée pour la récupération des identifiants (`agentidentity.authProviders.retrieveCredentials`)

Lorsque vous exécutez adk web localement ou que vous interagissez avec votre agent déployé, l'erreur 403 Forbidden suivante peut se produire :

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).

Cette erreur se produit, car le compte principal qui tente d'appeler le fournisseur d'authentification ne dispose pas des autorisations IAM requises pour récupérer les identifiants.

Pour résoudre cette erreur, attribuez le rôle Utilisateur d'identité d'agent (roles/agentidentity.user) au compte principal :

Si cette erreur se produit lors du développement local (uv run adk web ou uvicorn), assurez-vous d'avoir attribué le rôle à votre compte utilisateur personnel (user:USER_EMAIL).
Si cette erreur se produit lors de l'interaction avec un agent déployé, assurez-vous d'avoir attribué le rôle au compte principal de l'ID SPIFFE de votre agent (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Échec de déploiement générique

Lorsque vous déployez votre agent à l'aide de uv run adk deploy, la commande peut échouer avec un message d'erreur générique.

Cette erreur se produit en raison de dépendances Python manquantes, d'erreurs de syntaxe dans agent.py ou de variables d'environnement mal configurées.

Pour résoudre cette erreur, procédez comme suit :

Ouvrez la console Google Cloud , puis accédez à la page Explorateur de journaux.
Recherchez les journaux du conteneur de déploiement temporaire (par exemple, maps_mcp_agent_tmp... ou bigquery_mcp_agent_tmp...).
Vérifiez la trace Python pour identifier les erreurs de syntaxe ou les packages manquants.
Assurez-vous que tous les packages requis sont listés dans votre fichier requirements.txt.

Boucle d'authentification ServiceNow ou champs d'application inattendus

Lorsqu'un agent s'authentifie auprès de ServiceNow à l'aide d'OAuth à trois étapes, le flux d'authentification peut échouer ou l'agent peut entrer dans une boucle de requêtes.

Ce problème se produit, car ServiceNow détermine les champs d'application accordés au niveau de l'application plutôt qu'à partir des champs d'application demandés par l'agent. Si un administrateur configure des champs d'application spécifiques sur l'application ServiceNow (par exemple, useraccount), ServiceNow renvoie des jetons contenant uniquement ces champs d'application configurés, même si l'agent a demandé des champs d'application différents (par exemple, mcp_server). Si l'agent attend ou valide strictement les champs d'application demandés, il rejette le jeton reçu et peut demander à nouveau des identifiants dans une boucle.

Pour résoudre ce problème, procédez comme suit :

Connectez-vous à votre instance ServiceNow en tant qu'administrateur.
Accédez à la configuration de l'application ServiceNow OAuth.
Assurez-vous que tous les champs d'application requis par votre agent sont explicitement ajoutés à la liste des champs d'application autorisés pour l'application.
Configurez votre agent pour qu'il ne demande que les champs d'application activés dans ServiceNow.

Pour en savoir plus, consultez Services tiers compatibles.

Erreur liée à plusieurs champs d'application GitHub ou Microsoft

Lorsque vous configurez un fournisseur d'authentification pour GitHub ou Microsoft, l'authentification échoue si vous demandez plusieurs champs d'application OAuth.

Le gestionnaire d'authentification est compatible avec les intégrations à champ d'application unique pour GitHub et Microsoft. Le gestionnaire d'authentification n'est pas compatible avec la demande de plusieurs champs d'application simultanément.

Pour résoudre ce problème, configurez votre agent ou votre fournisseur d'authentification de sorte qu'il ne demande qu'un seul champ d'application nécessaire à l'intégration.

Pour en savoir plus, consultez Services tiers compatibles.

Erreurs de découverte OpenID Connect et de point de terminaison JWKS

Un service externe ou une partie de confiance peut interroger les points de terminaison Google CloudOpenID Connect Discovery (/.well-known/openid-configuration) ou JSON Web Key Set (/openid/jwks) du service de jeton de sécurité pour valider un jeton d'ID d'identité d'agent. Lorsque vous interrogez ces points de terminaison, la requête peut échouer avec une erreur HTTP 400, 404, 429 ou 500.

Le tableau suivant décrit les causes et les solutions de ces erreurs :

État HTTP	Cause	Solution
`400 Bad Request`	Cette erreur se produit, car le nom de ressource du pool d'identités de charge de travail dans l'URL de la requête n'est pas valide, ou la requête inclut un en-tête HTTP `Authorization`.	Pour résoudre cette erreur, procédez comme suit : Vérifiez que le nom de ressource du pool d'identités de charge de travail utilise un format de domaine de confiance d'agent compatible (`agents.global.org-ORGANIZATION_ID.system.id.goog` ou `agents.global.proj-PROJECT_NUMBER.system.id.goog`). Supprimez tous les en-têtes `Authorization` ou OAuth de la requête. Les points de terminaison `/.well-known/openid-configuration` et `/openid/jwks` sont publics et non authentifiés. La transmission d'en-têtes d'authentification entraîne l'échec de la requête avec une erreur `HTTP 400`.
`404 Not Found`	Cette erreur se produit, car l'ID d'organisation, le numéro de projet ou le pool d'identités de charge de travail spécifié n'existe pas, ou le chemin d'URL est incorrect.	Pour résoudre cette erreur, vérifiez que l'ID d'organisation, le numéro de projet et le domaine de confiance (ID du pool d'identités de charge de travail) dans l'URL sont corrects. Vérifiez également que le chemin d'accès de l'URL se termine par `/.well-known/openid-configuration` ou `/openid/jwks`.
`429 Too Many Requests`	Cette erreur se produit, car votre vérificateur a dépassé la limite de taux de demandes en interrogeant les points de terminaison de découverte ou JWKS sans mettre en cache la réponse.	Pour résoudre cette erreur, configurez votre vérificateur de sorte qu'il mette en cache le document de découverte et le JWKS pendant 24 heures maximum, conformément à l'en-tête de réponse `Cache-Control: public, max-age=86400, must-revalidate`.
`500 Internal Server Error`	Cette erreur se produit, car le serveur a rencontré un problème interne temporaire lors de la récupération des clés de signature publiques.	Pour résoudre cette erreur, utilisez votre JWKS mis en cache, si disponible, ou relancez la requête avec un intervalle exponentiel entre les tentatives.

Échec de la validation de la signature du jeton après la rotation des clés

Lorsqu'un service externe vérifie un jeton d'ID d'identité d'agent, la vérification de la signature peut échouer pour les jetons nouvellement émis, même si les jetons précédents du même agent ont été validés.

Ce problème se produit, car Google Cloud effectue régulièrement une rotation des clés de signature privées et publiques pour les pools d'identités de charge de travail. Par conséquent, il est possible que le kid (ID de clé) du jeton entrant ne se trouve pas dans le cache de clés local de votre vérificateur.

Pour résoudre ce problème, configurez votre vérificateur de sorte que, lorsqu'il reçoit un jeton avec un kid non reconnu, il récupère un nouveau JWKS à partir du point de terminaison /openid/jwks avant de rejeter le jeton.