Résoudre les problèmes liés aux règles d'accès unifiées IAM

Ce document vous aide à diagnostiquer et à résoudre les problèmes courants lors de la configuration et de l'application des règles d'accès unifiées (UAP, Unified Access Policies) IAM pour la sortie Agent Gateway.

Échec de l'application des règles et de l'accès

Cette section décrit les problèmes liés à l'application des règles.

La règle n'est pas appliquée

Symptôme : Un agent peut accéder aux outils de destination, aux serveurs MCP ou aux points de terminaison même si une règle de refus IAM ou une règle d’autorisation restrictive a été configurée pour bloquer l’accès.

Cause : L'extension d'autorisation Agent Gateway s'exécute en mode dry run ou le champ d'application de la liaison de règle ne correspond pas à la ressource cible. En mode dry run, les décisions d'accès sont évaluées et consignées à des fins d'audit, mais les requêtes ne sont jamais bloquées.

Solution:

  1. Passez du mode dry run au mode d'application : commencez par vérifier le fichier de configuration de votre extension d'autorisation (iap-request-authz-extension.yaml). Si iamEnforcementMode est défini sur "DRY_RUN", remplacez-le par "ENFORCE" (ou supprimez le paramètre DRY_RUN) et réimportez l'extension à l'aide de gcloud CLI :

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    Remplacez les éléments suivants :

    • EXTENSION_NAME: nom de votre extension d'autorisation
    • EXTENSION_FILE: nom de fichier de votre configuration d'extension YAML
    • LOCATION : Cloud de Confiance région où votre passerelle est déployée

  2. Vérifiez la délégation de la règle d'autorisation de la passerelle : vérifiez que votre règle d'autorisation de la passerelle (policyProfile: REQUEST_AUTHZ) est liée à l'instance Agent Gateway appropriée (target.resources).

  3. Vérifiez le champ d'application de la liaison de règle : vérifiez que l'UAP IAM est liée au champ d'application de la ressource cible où le trafic arrive.

  4. Inspectez la priorité des règles : dans une règle combinée, les règles de refus remplacent explicitement les règles d'autorisation au même champ d'application. Toutefois, vérifiez si une UAP avec une règle d'autorisation plus large liée au niveau du registre ou du projet accorde l'accès sans restrictions de condition.

Le règlement relatif à l'application des règles bloque l'accès de l'agent

Symptôme : La requête de sortie d'un agent échoue avec une erreur HTTP 403 Forbidden ou PERMISSION_DENIED lorsque l'application de la règle Agent Gateway est activée.

Causes:

  • L'identité de l'agent n'est pas spécifiée dans l'UAP.

  • L'identité de l'agent n'a pas reçu l'autorisation iap.resources.egressViaIAP sur la ressource de destination.

  • Le nom d'hôte de destination exact n'est pas enregistré dans Agent Registry.

  • Les attributs de la requête ne répondent pas aux conditions CEL (Common Expression Language) de l'UAP.

Solution:

  1. Passez en mode dry run pour un débogage non perturbateur : lors du diagnostic de l'échec, passez temporairement l'extension d'autorisation en mode dry run (iamEnforcementMode: "DRY_RUN") afin que le trafic de l'agent actif ne soit pas bloqué pendant que vous inspectez les journaux d'audit.

  2. Interrogez les journaux d'audit Cloud : interrogez les journaux d'audit Cloud pour inspecter la vérification d'autorisation exacte et l'évaluation des attributs CEL :

    gcloud

    Exécutez la commande gcloud logging read suivante :

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    Remplacez PROJECT_ID par l'ID du projet.

    Console

    1. Dans la Cloud de Confiance console, accédez à la page Explorateur de journaux.
    2. Sélectionnez votre projet.
    3. Dans Query editor (éditeur de requête), saisissez la requête suivante : 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. Cliquez sur Exécuter la requête.
    5. Développez l'entrée de journal et inspectez protoPayload.authorizationInfo pour voir l'URI de la ressource cible et l'autorisation dont l'évaluation a échoué.

  3. Vérifiez la correspondance exacte du nom d'hôte : Agent Gateway fait correspondre les noms d'hôte de destination exactement. Une API Google ou un service tiers peut se résoudre via plusieurs variantes de nom d'hôte en fonction de la version du SDK , de la configuration régionale du client ou de l'utilisation de mTLS. Par exemple, us-central1-aiplatform.googleapis.com par rapport à us-central1-aiplatform.mtls.googleapis.com par rapport à aiplatform.googleapis.com.

    • Si vous vous appuyez sur des cibles enregistrées, assurez-vous que chaque variante exacte du nom d'hôte est enregistrée dans Agent Registry.
    • Si l'agent accède à des points de terminaison non enregistrés, vérifiez qu'une règle de point de terminaison non enregistré accorde iap.resources.egressViaIAP pour cet hôte et ce chemin d'accès.

  4. Vérifiez la couverture de la liaison de règle dans tous les champs d'application : vérifiez si une liaison de règle existe dans l'un des trois champs d'application compatibles :

    • À l'échelle du registre : accorde l'accès à tous les agents, serveurs MCP et points de terminaison du registre.
    • Par ressource : accorde l'accès à un serveur MCP, un point de terminaison ou un agent enregistré spécifique.
    • Points de terminaison non enregistrés : accorde l'accès aux destinations en dehors d' Agent Registry.
    • Remarque : Lorsque vous décrivez les liaisons de règles pour une ressource cible, si la sortie renvoyée contient un champ "etag" mais aucune liaison, aucune règle IAM n'existe pour cette cible.

Messages d'erreur courants de l'UI, de gcloud et de l'API REST

Cette section décrit les messages d'erreur et explique comment les résoudre.

Règle introuvable

Message d'erreur :

  • UI de la console : "La règle demandée n'existe pas. Vérifiez que la règle existe pour la ressource sélectionnée."
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Cause : L'ID UAP spécifié dans votre requête de mise à jour ou votre liaison de règle n'existe pas dans le projet ou l'emplacement, ou a été supprimé.

Solution : Répertoriez toutes les UAP disponibles dans votre projet à l'aide de gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global pour confirmer l'ID et l'emplacement exacts de la règle avant de la lier ou de la mettre à jour.

Limite de liaisons de cibles dépassée

Message d'erreur :

  • UI de la console : "La cible sélectionnée a atteint sa limite de liaisons de règles d'accès. Supprimez une liaison existante avant d'en ajouter une."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Cause : Vous avez tenté d'associer plus de liaisons de règles à une ressource cible (telle qu'un serveur MCP ou un registre) que la limite maximale autorisée par cible.

Solution : Au lieu de créer une UAP et une liaison distinctes pour chaque règle individuelle, regroupez plusieurs règles d’autorisation ou de refus dans une seule UAP. Supprimez les liaisons inutilisées à l'aide de gcloud iam policy-bindings delete.

Limite de liaisons de règles dépassée

Message d'erreur :

  • UI de la console : "La règle sélectionnée a atteint sa limite de liaisons. Supprimez une liaison existante avant d'en ajouter une."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Cause : Une seule UAP est associée à un nombre trop important de ressources cibles distinctes dans votre projet.

Solution : Liez la règle à un champ d'application plus large, tel que le champ d'application à l'échelle du registre (AgentRegistry) ou le champ d'application du projet, et utilisez des conditions d'attribut CEL (telles que destination.agent_registry.mcp_server.name) pour régir l'accès aux outils individuels dans les règles de la règle.

Limite de conditions dépassée

Message d'erreur :

  • UI de la console : "Cette règle a atteint le nombre maximal de conditions d'attribut. Supprimez certaines conditions pour enregistrer vos modifications."
  • API / gcloud : TOO_MANY_CONDITIONS / Limite de conditions dépassée pour la règle dans la règle.

Cause : Une seule règle d'autorisation ou de refus contient plus de conditions d'attribut de contrôle des accès ultraprécis (FGAC, Fine-Grained Access Control) ou de sous-expressions complexes que celles acceptées dans une seule règle.

Solution : Regroupez les vérifications d'attributs à l'aide d'opérateurs logiques CEL (&&, ||) ou définissez des recherches d'inclusion (in), ou divisez vos expressions en plusieurs règles dans la même UAP.

Détails de la règle obsolètes

Message d'erreur :

  • UI de la console : "Les détails de la règle sont obsolètes. Cette règle a été modifiée par un autre utilisateur après le chargement de cette page. Actualisez la page pour récupérer les détails actuels avant toute modification ou suppression."
  • API / gcloud : HTTP 412 Precondition Failed / ABORTED en raison d'une non-concordance etag.

Cause : Un autre administrateur ou un processus automatisé a modifié l' UAP après que vous l'avez récupérée, ce qui a entraîné une différence entre l' etag et l'état actif du serveur.

Solution : Actualisez la page de la console pour récupérer les détails de la règle active et etag avant d’enregistrer vos modifications. Lorsque vous utilisez l'API REST, effectuez d'abord une GET requête pour récupérer la valeur active "etag", puis incluez-la dans la charge utile de votre PATCH requête.

Impossible de supprimer la dernière règle d'une règle

Message d'erreur :

  • UI de la console: "Impossible de supprimer cette règle. La 'règle par défaut' doit contenir au moins une règle. Pour supprimer cette règle, supprimez plutôt la règle." ou "Il s'agit de la dernière règle de <nom de la règle>. Si vous la supprimez, la règle sera également supprimée, ainsi que toutes les liaisons associées, ce qui peut affecter l'accès de l'agent aux ressources."

Cause : Une UAP IAM ne peut pas être enregistrée sans aucune règle.

Solution : Si vous souhaitez supprimer la seule règle d'une règle, supprimez l' intégralité de la règle. N'oubliez pas que vous devez supprimer toutes les liaisons de règles qui font référence à la règle avant de pouvoir supprimer la règle elle-même.

Expression CEL personnalisée conservée dans l'onglet "Avancé"

Message d'erreur :

  • UI de la console : "L'expression CEL personnalisée n'a pas pu être convertie en sélections d'UI standards. Votre expression est conservée dans l'onglet "Avancé"."

Cause : Vous avez saisi une condition ou une fonction CEL complexe dans l'éditeur de conditions (onglet "Avancé") qui ne peut pas être mappée dans les sélecteurs de liste déroulante simplifiés du générateur de conditions standard.

Solution : Ce message est une notification d'information. Votre condition CEL personnalisée est valide et conservée. Continuez à apporter des modifications directement dans l'onglet Éditeur de conditions.

Étape suivante