Déléguer l'autorisation avec des extensions de service

Cette page vous explique comment déléguer l'autorisation pour Agent Gateway à Identity-Aware Proxy, Model Armor et d'autres moteurs d'autorisation personnalisés à l'aide des Service Extensions.

Règles et extensions d'autorisation

Les règles d'autorisation vous permettent d'appliquer des règles de gouvernance et de contrôle des accès centralisées au trafic transitant par les points de terminaison publiés par Agent Gateway. Pour gérer les décisions complexes concernant le contrôle des accès, la sécurité du contenu et la gouvernance, Agent Gateway vous permet de configurer des règles d'autorisation avec des extensions d'autorisation qui vous permettent de déléguer les décisions concernant l'autorisation et la sécurité du contenu aux moteurs d'autorisation désignés de votre choix.

Une extension d'autorisation intercepte les requêtes qui transitent par un déploiement Agent Gateway et effectue un appel gRPC en temps réel au service d'autorisation désigné. Cela permet au service d'inspecter, de modifier ou de bloquer le trafic avant qu'il ne poursuive sa route vers sa destination. Vous pouvez déléguer l'autorisation à des services Cloud de Confiance tels qu'Identity-Aware Proxy, Model Armor et les règles de gouvernance sémantique, ou à n'importe quel moteur d'autorisation personnalisé de votre choix.

Les règles d'autorisation utilisent des profils de règles pour déterminer le type de données de trafic envoyées à l'extension d'autorisation :

• Autorisation basée sur les requêtes (REQUEST_AUTHZ) : évalue les en-têtes de requête HTTP avant le traitement de toute charge utile d'application. Ce profil est utilisé pour la validation de l'identité et le contrôle des accès, par exemple pour déléguer l'autorisation à Identity-Aware Proxy.
• Autorisation basée sur le contenu (CONTENT_AUTHZ) : évalue les charges utiles complètes des requêtes et des réponses HTTP. Ce profil est utilisé pour l'inspection approfondie du contenu et la sécurité de l'IA, par exemple en déléguant à Model Armor pour la sécurité des requêtes et des réponses ou aux Règles de gouvernance sémantique pour l'application des contraintes en langage naturel.

Les moteurs d'autorisation personnalisés peuvent utiliser les extensions REQUEST_AUTHZ ou CONTENT_AUTHZ selon qu'ils inspectent les en-têtes ou les charges utiles complètes des applications.

Vous pouvez configurer les extensions d'autorisation séparément pour les règles basées sur les requêtes et celles basées sur le contenu, ou combiner les deux sur une passerelle pour une sécurité complète. Pour connaître les configurations recommandées, consultez Configuration recommandée pour l'entrée et la sortie.

Pour en savoir plus sur les règles d'autorisation, les profils de règles et leurs cas d'utilisation, consultez Présentation des règles d'autorisation.

Configuration d'entrée et de sortie recommandée

Pour une sécurité complète tout au long du cycle de vie de l'agent, nous vous recommandons le modèle d'architecture multi-passerelle suivant :

• Passerelles client vers agent : les passerelles client vers agent (entrée) n'acceptent qu'une seule règle CONTENT_AUTHZ. Cela signifie que vous ne pouvez pas utiliser les stratégies Model Armor et de gouvernance sémantique ensemble pour l'entrée. Nous vous recommandons vivement d'utiliser une stratégie Model ArmorCONTENT_AUTHZ pour vous protéger contre les attaques par injection de prompt. Toutefois, si vous souhaitez utiliser une extension de règle de gouvernance sémantique, vous devez vous assurer que Model Armor n'est pas configuré sur la passerelle. Les autres types d'extensions de service ne sont pas compatibles avec les passerelles d'entrée.

• Passerelles Agent-to-Anywhere : les passerelles Agent-to-Anywhere (sortie) sont compatibles avec un maximum de quatre règles d'autorisation. Les passerelles de sortie sont compatibles avec les profils de règles REQUEST_AUTHZ et CONTENT_AUTHZ. Vous pouvez configurer plusieurs règles de chaque type dans cette limite.

  Nous vous recommandons la configuration suivante :

  • Une règle REQUEST_AUTHZ déléguant à Identity-Aware Proxy (IAP) pour autoriser l'identité de l'agent.
  • Une ou plusieurs règles CONTENT_AUTHZ délégant d'autres décisions à Model Armor ou à des règles de gouvernance sémantique pour protéger contre l'exposition de données sensibles et appliquer des contraintes en langage naturel aux appels et réponses d'outils sortants.

  Pour en savoir plus sur l'évaluation des règles, consultez Évaluation des règles sur la sortie.

Cette topologie multi-passerelles garantit que Model Armor filtre les requêtes entrantes, tandis que les règles IAP, Model Armor et de gouvernance sémantique filtrent les réponses sortantes.

Évaluation des règles sur la sortie

Lorsqu'une passerelle de sortie est configurée avec plusieurs règles d'autorisation, elles sont évaluées séquentiellement en fonction de leur type de profil de règle :

1. Règles REQUEST_AUTHZ (basées sur les en-têtes) : ces types de règles sont évalués en premier. Par exemple, une extension IAP vérifie l'identité mTLS de l'agent appelant et valide ses règles d'autorisation IAM avant tout traitement du contenu. Si la requête échoue à cette vérification, elle est immédiatement refusée.
2. Règles CONTENT_AUTHZ (basées sur le contenu) : ces types de règles sont évalués ensuite. Si la demande réussit la vérification basée sur l'en-tête, la charge utile est diffusée en continu à l'extension d'autorisation basée sur le contenu (telle que le moteur de règles de gouvernance sémantique) pour une inspection approfondie du contenu et une évaluation de la conformité.

Avant de commencer

Avant de commencer, assurez-vous de remplir les conditions suivantes :

• L'Agent Gateway est déployée. Consultez Configurer la passerelle de l'agent.

• Vous devez disposer de l'autorisation IAM networkservices.agentGateways.use sur la ressource Agent Gateway déployée pour pouvoir associer des stratégies d'autorisation à la passerelle.

Configurer des règles d'autorisation avec des extensions

Cette section explique comment configurer des règles d'autorisation qui délèguent les décisions d'autorisation et de sécurité du contenu à Identity-Aware Proxy, Model Armor et d'autres services personnalisés.

Déléguer l'autorisation à IAP

Vous pouvez configurer une extension d'autorisation des requêtes pour déléguer les décisions d'accès pour les règles d'autorisation à IAP.

Les étapes suivantes vous montrent comment configurer une extension d'autorisation avec une règle d'autorisation pour une instance Agent Gateway.

1. Avant de commencer : Désactivez l'application de la contrainte de règle d'administration gérée Désactiver l'accès à la liaison à la ressource (constraints/iam.managed.disableAccessPolicyBindings). Par défaut, cette contrainte booléenne est activée pour les nouvelles organisations et vous empêche d'associer une règle d'accès unifiée IAM à une ressource. Pour en savoir plus, consultez Mettre à jour des règles avec des règles booléennes.

2. Créez les règles de sortie IAM requises pour vos agents et outils. Pour en savoir plus, consultez Créer des règles d'agent IAM.

3. Consultez Configurer l'Agent Gateway en mode Agent-to-Anywhere (sortie) pour activer IAP lors de la création de l'Agent Gateway (à l'aide du paramètre Autorisation d'accès).

4. Configurez une extension d'autorisation pour qu'elle pointe vers IAP.

   1. Définissez l'extension dans un fichier YAML. Utilisez les exemples de valeurs fournis. Si vous souhaitez déployer l'extension en mode dry run (audit uniquement) pour tester la règle d'autorisation sans l'appliquer, vous pouvez spécifier le champ iamEnforcementMode dans le bloc metadata.

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      

      Si vous souhaitez déployer l'extension en mode dry run (audit uniquement) pour tester la règle d'autorisation sans l'appliquer, vous pouvez spécifier le champ iamEnforcementMode dans le bloc metadata. Cela vous permet de vérifier votre règle et de minimiser le risque d'interruption du trafic en raison d'erreurs de configuration :

      cat >iap-request-authz-extension.yaml <<EOF
      name: my-iap-request-authz-ext
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        iamEnforcementMode: "DRY_RUN"
      EOF
      

      Supprimez le champ iamEnforcementMode: "DRY_RUN" du bloc metadata lorsque vous êtes prêt à commencer à appliquer des règles.

   2. Importez l'extension d'autorisation. Utilisez la commande gcloud service-extensions authz-extensions import avec les exemples de valeurs suivants.

      gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
          --source=iap-request-authz-extension.yaml \
          --location=LOCATION
      

5. Dans le même projet, configurez une règle d'autorisation qui délègue la décision à l'extension.

   1. Définissez une règle d'autorisation qui associe l'extension my-iap-request-authz-ext à votre passerelle. Utilisez les exemples de valeurs fournis.

      cat >iap-request-authz-policy.yaml <<EOF
      name: my-iap-request-authz-policy
      target:
        resources:
          - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: REQUEST_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
            - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-iap-request-authz-ext"
      EOF
      

      Remplacez PROJECT_ID par votre ID de projet.

   2. Importez la stratégie d'autorisation dans le projet. Utilisez la commande gcloud network-security authz-policies import avec les exemples de valeurs suivants.

      gcloud network-security authz-policies import my-iap-request-authz-policy \
          --source=iap-request-authz-policy.yaml \
          --location=LOCATION
      

Déléguer l'autorisation à Model Armor

Vous pouvez configurer une extension d'autorisation pour déléguer les décisions de sécurité du contenu pour les règles d'autorisation à Model Armor.

L'exemple suivant montre comment configurer une telle extension d'autorisation avec une règle d'autorisation pour Agent Gateway.

Déléguer l'autorisation à des extensions d'autorisation personnalisées

Vous pouvez configurer des extensions d'autorisation personnalisées pour déléguer des décisions à des services personnalisés. Ces extensions personnalisées ne peuvent cibler que des noms de domaine complets.

Lorsque vous utilisez des cibles de nom de domaine complet, l'extension utilise le protocole HTTP2 avec le chiffrement TLS pour communiquer avec les points de terminaison sur le port 443. Toutefois, l'extension ne valide pas le certificat du serveur. Par conséquent, pour une meilleure sécurité, vous devez vous assurer que les points de terminaison résolus se trouvent dans le réseau VPC. Assurez-vous également d'avoir configuré l'appairage DNS entre le projet Agent Gateway et votre réseau VPC.

1. Pour configurer une extension d'autorisation avec une règle d'autorisation pour un nom de domaine complet spécifique, tel que mycustomauthz.internal.net, spécifiez-le comme valeur pour service dans le fichier YAML de l'extension, comme le montre l'exemple suivant. Cet exemple suppose que vous avez déployé un serveur dans votre réseau VPC implémentant le protocole ext_proc en mode de traitement du corps FULL_DUPLEX_STREAMED.

   cat >custom-authz-extension.yaml <<EOF
   name: my-custom-authz-ext
   service: mycustomauthz.internal.net
   failOpen: false
   timeout: 1s
   EOF
   

2. Créez l'extension d'autorisation pour qu'elle pointe vers le service personnalisé.

   gcloud beta service-extensions authz-extensions import custom-authz-extension \
     --source=custom-authz-extension.yaml \
     --location=LOCATION
   

3. Après avoir créé l'extension, configurez une règle d'autorisation CUSTOM qui délègue les décisions à l'extension d'autorisation.

     cat >authz-policy.yaml <<EOF
     name: authz-with-extension
     target:
       resources:
         - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
     policyProfile: CONTENT_AUTHZ
     action: CUSTOM
     customProvider:
       authzExtension:
         resources:
           - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension"
     EOF
   

4. Créez la règle d'autorisation.

   gcloud network-security authz-policies import authz-policy-with-extension \
   --source=authz-policy.yaml \
   --location=LOCATION
   

Notez que lorsqu'une extension d'autorisation est associée à une règle d'autorisation à l'aide du profil CONTENT_AUTHZ, comme illustré dans cet exemple, la passerelle appelle l'extension pour les charges utiles de requête et de réponse (en-têtes et corps), ce qui permet une inspection approfondie du contenu, des garde-fous pour les requêtes et la désinfection des données pour le trafic de votre agent. Par défaut, les règles CONTENT_AUTHZ utilisent le protocole Envoy ext_proc en mode FULL_DUPLEX_STREAMED pour traiter les événements de corps.

Combiner l'autorisation IAP avec les garde-fous Model Armor

Pour une sécurité complète, nous vous recommandons de configurer une règle d'autorisation PERSONNALISÉE avec un profil de règle REQUEST_AUTHZ et une autre règle d'autorisation PERSONNALISÉE avec un profil de règle CONTENT_AUTHZ.

L'exemple suivant utilise IAP comme système centralisé d'autorisation des requêtes et Model Armor pour les garde-fous de l'IA. Comme indiqué dans les exemples précédents, vous pouvez remplacer chacun de ces éléments par des extensions de service pour utiliser vos propres solutions personnalisées.

1. Configurez une extension d'autorisation REQUEST_AUTHZ qui délègue à IAP et une règle d'autorisation qui pointe vers l'extension.

   1. Définissez l'extension d'autorisation. Le champ iapPolicyVersion sous metadata est obligatoire.

      cat >iap-extension.yaml <<EOF
      name: iap-extension
      service: iap.googleapis.com
      failOpen: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
      EOF
      

   2. Créez l'extension d'autorisation.

      gcloud service-extensions authz-extensions import iap-extension \
      --source=iap-extension.yaml \
      --location=LOCATION
      

      Remplacez LOCATION par la région de l'extension.

   3. Configurez la règle d'autorisation REQUEST_AUTHZ qui délègue à l'extension.

      cat >authz-policy-request-authz.yaml <<EOF
      name: authz-iap
      target:
        resources:
        - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: REQUEST_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
          - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/iap-extension"
      EOF
      

      Remplacez les éléments suivants :

      • PROJECT_ID : ID du projet.
      • LOCATION : emplacement des ressources.
      • AGENT_GATEWAY_NAME : nom de la passerelle d'agent.

   4. Créez la règle d'autorisation.

      gcloud network-security authz-policies import authz-iap \
      --source=authz-policy-request-authz.yaml \
      --location=LOCATION
      

2. Configurez une extension d'autorisation CONTENT_AUTHZ qui délègue à Model Armor et une règle d'autorisation qui pointe vers l'extension.

   1. Définissez l'extension.

      cat >ma-extension-file.yaml <<EOF
      name: ma-extension
      service: modelarmor.LOCATION.rep.googleapis.com
      metadata:
        model_armor_settings: '[
          {
          "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE_ID",
          "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/REQUEST_TEMPLATE_ID"
          }
        ]'
      failOpen: false
      timeout: 1s
      EOF
      

      Remplacez les éléments suivants :

      • LOCATION : région dans laquelle résident vos modèles Model Armor.
      • MODEL_ARMOR_PROJECT_ID : ID du projet contenant les modèles Model Armor.
      • RESPONSE_TEMPLATE_ID : ID du modèle de réponse.
      • REQUEST_TEMPLATE_ID : ID du modèle de requête.

   2. Créez l'extension d'autorisation.

      gcloud service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      

   3. Configurez la règle d'autorisation CONTENT_AUTHZ qui délègue à l'extension.

      cat >authz-policy-content-authz.yaml <<EOF
      name: authz-ma
      target:
        resources:
        - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
      policyProfile: CONTENT_AUTHZ
      action: CUSTOM
      customProvider:
        authzExtension:
          resources:
          - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/ma-extension"
      EOF
      

   4. Créez la règle d'autorisation.

      gcloud network-security authz-policies import ma-authz-policy \
      --source=authz-policy-content-authz.yaml \
      --location=LOCATION
      

Lorsqu'une extension d'autorisation est associée à un profil CONTENT_AUTHZ, elle reçoit tous les événements ext_proc, y compris les en-têtes, le corps et les trailers de requête et de réponse. Si votre extension d'autorisation basée sur ext_proc est capable de gérer à la fois l'autorisation au moment de la requête et l'autorisation basée sur le contenu, nous vous recommandons de configurer une seule règle d'autorisation CUSTOM avec le profil de règle CONTENT_AUTHZ. Cette règle doit pointer vers votre extension d'autorisation polyvalente. Cette approche permet les deux types d'autorisation via une seule extension et une seule connexion ext_proc, ce qui peut améliorer les profils de latence.

Déléguer l'autorisation aux règles de gouvernance sémantique

Vous pouvez configurer une extension d'autorisation pour déléguer les décisions concernant le filtrage des intentions et les contraintes en langage naturel pour les règles d'autorisation au moteur de règles de gouvernance sémantique (semanticGovernancePolicyEngine).

Pour savoir comment provisionner le moteur de règles et créer la liaison de stratégie d'autorisation et d'extension d'autorisation CONTENT_AUTHZ requise sur votre passerelle, consultez Connecter le moteur de règles à Agent Gateway.

Autorisation basée sur les attributs du protocole MCP

Agent Gateway analyse la charge utile du protocole MCP dans une requête et met les attributs extraits à la disposition des règles d'autorisation.

Vous pouvez restreindre l'accès en fonction des paramètres de la méthode MCP, tels que les noms d'outils spécifiques. Cette section présente deux exemples, l'un pour une stratégie ALLOW et l'autre pour DENY.

1. Configurez la règle d'autorisation.

   Exemple de règle : ALLOW

   Cet exemple autorise l'accès à un ensemble spécifique d'outils sur le serveur MCP et aux fonctionnalités de protocole de base, mais interdit l'accès aux invites et aux ressources.

   Lorsque vous écrivez une règle ALLOW, assurez-vous de spécifier baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS afin que les RPC MCP non spécifiques à l'accès, tels que l'initialisation, la journalisation, l'achèvement, les notifications et le ping, continuent de fonctionner. Dans le cas contraire, vous ne pourrez pas établir de session MCP.

   cat >authz-policy-restrict-tools.yaml <<EOF
   name: my-authz-policy-restrict-tools
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   policyProfile: REQUEST_AUTHZ
   httpRules:
   - to:
       operations:
       - mcp:
           baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS
           methods:
           - name: "tools/list"
           - name: "tools/call"
             params:
             - exact: "get_weather"
             - exact: "get_location"
   action: ALLOW
   EOF
   

   Exemple de règle : DENY

   Cet exemple interdit l'accès à toutes les invites/ méthodes à un serveur MCP derrière une passerelle d'agent.

   cat >authz-policy-disallow-prompts.yaml <<EOF
   name: my-authz-policy-disallow-prompts
   target:
     resources:
     - "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
   policyProfile: REQUEST_AUTHZ
   httpRules:
   - to:
       operations:
       - mcp:
           methods:
           - name: "prompts"
   action: DENY
   EOF
   

2. Créez la règle d'autorisation.

   gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
   --source=AUTH_POLICY_YAML_FILE_PATH \
   --location=LOCATION
   

   Remplacez les éléments suivants :

   • AUTHZ_POLICY_NAME : nom de la règle d'autorisation.
   • AUTH_POLICY_YAML_FILE_PATH : chemin d'accès au fichier YAML de la règle d'autorisation.
   • LOCATION : emplacement des ressources.

Limites

Les limites suivantes s'appliquent lorsque vous utilisez des règles d'autorisation :

• Le nombre maximal de règles d'autorisation par passerelle dépend du mode de la passerelle :

  • Pour les passerelles Agent-to-Anywhere (sortie), vous pouvez configurer un maximum de quatre règles d'autorisation par passerelle, quel que soit le profil de règle (REQUEST_AUTHZ ou CONTENT_AUTHZ).
  • Pour les passerelles Client-to-Agent (entrée), vous pouvez configurer une seule règle CONTENT_AUTHZ.

  Pour en savoir plus, consultez Configuration d'entrée et de sortie recommandée.

• Si vous utilisez des extensions d'autorisation personnalisées avec le profil CONTENT_AUTHZ, elles doivent être compatibles avec le protocole ext_proc et le mode FULL_DUPLEX_STREAMED pour les événements de corps.

• Si vous configurez plusieurs règles d'autorisation personnalisées qui utilisent le même profil, leur ordre d'exécution n'est pas garanti.

Pour en savoir plus sur les limites des extensions d'autorisation, consultez également les sections suivantes :

• Pour connaître les limites applicables à toutes les extensions, consultez Limites des extensions.

• Pour connaître les limites applicables aux encarts, consultez Limites des encarts.

Étapes suivantes