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

Ce document explique comment résoudre les erreurs courantes lors de l'utilisation du gestionnaire d'authentification Agent Identity.

Pour obtenir des instructions sur la configuration des fournisseurs d'authentification, consultez Gérer les fournisseurs d'authentification de l'identité de l'agent.

Incohérence de l'URI de redirection

Si vous recevez une erreur redirect URI mismatch de l'application tierce lors du 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, accordez le rôle à l'aide de la console Google Cloud ou exécutez la commande add-iam-policy-binding.

Problèmes liés aux points de terminaison de l'émetteur

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

Si Google Cloud ne parvient 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 si vous avez des exigences spécifiques concernant le partage de jetons ou si vous devez injecter le jeton directement dans l'en-tête. Pour désactiver cette fonctionnalité, définissez la variable d'environnement suivante lorsque vous déployez votre agent :

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": 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 parce que 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 assurez-vous 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éder à API et services > Identifiants

Clé API non valide (`API_KEY_INVALID`)

L'erreur suivante peut se produire lorsque vous envoyez des requêtes à un service tiers. 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, mal formée ou n'existe pas dans les identifiants de votre projet.

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

Autorisation refusée pour récupérer les identifiants (`agentidentity.authProviders.retrieveCredentials`)

Lorsque vous exécutez adk web en local 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é de l'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 lorsque vous interagissez avec un agent déployé, assurez-vous d'avoir accordé le rôle au 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 générique du déploiement

Lorsque vous déployez votre agent à l'aide de uv run adk deploy, la commande peut échouer et afficher 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 et 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 suivre 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ête.

Ce problème se produit, car ServiceNow détermine les niveaux d'accès accordés au niveau de l'application plutôt qu'à partir des niveaux d'accès demandés par l'agent. Si un administrateur configure des niveaux d'accès spécifiques dans l'application ServiceNow (par exemple, useraccount), ServiceNow renvoie des jetons contenant uniquement ces niveaux d'accès configurés, même si l'agent a demandé des niveaux d'accès différents (tels que mcp_server). Si l'agent s'attend strictement aux niveaux d'accès demandés ou les valide, il rejette le jeton reçu et peut demander à nouveau les identifiants en 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 niveaux d'accès requis par votre agent sont explicitement ajoutés à la liste des niveaux d'accès autorisés pour l'application.
Configurez votre agent pour qu'il ne demande que les autorisations activées dans ServiceNow.

Pour en savoir plus, consultez Services tiers compatibles.

Erreur liée à plusieurs niveaux d'accès GitHub ou Microsoft

Lorsque vous configurez un fournisseur d'authentification pour GitHub ou Microsoft, l'authentification échoue si vous demandez plusieurs niveaux d'accès OAuth.

Le gestionnaire d'authentification est compatible avec les intégrations à portée unique pour GitHub et Microsoft. Le gestionnaire d'authentification n'accepte pas les demandes de plusieurs niveaux d'accès simultanément.

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