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

Ce document explique comment résoudre les erreurs courantes d'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 Google Cloud console ou exécutez la commande gcloud suivante :

gcloud alpha agent-identity connectors 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/iamconnectors.user sur la ressource du fournisseur d'authentification.

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

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 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 parvient 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 en matière de partage de jetons ou que vous devez injecter le jeton directement dans l'en-tête. Pour désactiver cette règle, 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 Google Cloud projet ou que les restrictions de la clé API n'autorisent pas l'accès à ce service.

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

  1. Dans la Google Cloud console, accédez à la page API et services >Bibliothèque et assurez-vous que l'API cible est activée.

    Accéder à API et services >Bibliothèque

  2. Dans la Google Cloud console, 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)

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, mal formée ou n'existe pas dans vos identifiants de projet.

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

Autorisation refusée lors de la récupération des identifiants (iamconnectors.connectors.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://iamconnectorcredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'iamconnectors.connectors.retrieveCredentials' denied on resource '//iamconnectors.googleapis.com/projects/PROJECT_ID/locations/LOCATION/connectors/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 du connecteur (roles/iamconnectors.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 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 générique du déploiement

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 :

  1. Ouvrez la Google Cloud console et accédez à la page Explorateur de journaux.
  2. Recherchez les journaux du conteneur de déploiement temporaire (par exemple, maps_mcp_agent_tmp... ou bigquery_mcp_agent_tmp...).
  3. Vérifiez l'arborescence Python pour identifier l'erreur de syntaxe ou suivre les packages manquants.
  4. Assurez-vous que tous les packages requis sont listés dans votre fichier requirements.txt.

Étape suivante