Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Ce document explique comment résoudre les erreurs courantes liées à l'authentification à l'aide de l'identité de l'agent avec le gestionnaire d'authentification.

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 n'est pas protégé par un pare-feu ni limité à 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 stratégie 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 votre 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'espaces blancs 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 attribué 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.