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 extensions de service.

Règles d'autorisation et extensions

Les règles d'autorisation vous permettent d'appliquer des règles centralisées de contrôle des accès et de gouvernance au trafic transitant par les points de terminaison publiés par Agent Gateway. Pour gérer les décisions complexes de contrôle des accès, de sécurité du contenu et de 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 d'autorisation et de sécurité du contenu aux moteurs d'autorisation désignés de votre choix.

Une extension d'autorisation intercepte les requêtes transitant 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 continue vers sa destination. Vous pouvez déléguer l'autorisation à des services Google Cloud 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 réponses HTTP. Ce profil est utilisé pour l'inspection approfondie du contenu et la sécurité de l'IA, par exemple pour déléguer à Model Armor la sécurité des prompts et des réponses, ou à des règles de gouvernance sémantique l'application de contraintes en langage naturel.

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

Vous pouvez configurer des 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 d'entrée et de sortie recommandée.

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.

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 Model Armor et les règles de gouvernance sémantique ensemble pour l'entrée. Nous vous recommandons vivement d'utiliser une règle Model Armor CONTENT_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) acceptent jusqu'à 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 stratégie REQUEST_AUTHZ déléguant à Identity-Aware Proxy (IAP) l'autorisation de l'identité de l'agent.
    • Une ou plusieurs règles CONTENT_AUTHZ déléguant 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 de langage naturel aux appels d'outils et aux réponses sortants.

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

Cette topologie multigateway garantit que Model Armor filtre les prompts entrants, tandis qu'IAP, Model Armor et les règles de gouvernance sémantique filtrent les réponses sortantes.

Évaluation des règles à la sortie

Lorsque plusieurs règles d'autorisation sont configurées sur une passerelle de sortie, elles sont évaluées de manière séquentielle 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 stratégies d'autorisation IAM avant que tout contenu ne soit traité. Si la requête échoue à cette vérification, elle est immédiatement rejetée.
  2. Règles CONTENT_AUTHZ (basées sur le contenu) : ces types de règles sont évalués ensuite. Si la requête réussit la vérification basée sur l'en-tête, la charge utile est transmise à l'extension d'autorisation basée sur le contenu (comme le moteur de stratégies 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 Agent Gateway.

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

Configurer des règles d'autorisation avec des extensions

Cette section vous 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 de requête pour déléguer les décisions d'accès pour les règles d'autorisation à IAP.

Les étapes suivantes vous expliquent 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 la liaison de la règle d'accès à la ressource (constraints/iam.managed.disableAccessPolicyBindings). Par défaut, cette contrainte booléenne est activée pour les nouvelles organisations et vous empêche de lier une règle d'accès unifié 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 vos outils. Pour en savoir plus, consultez Créer des règles d'agent IAM.

  3. Consultez Configurer Agent Gateway en mode Agent-to-Anywhere (sortie) pour activer IAP lors de la création d'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-only, 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-only, pour tester la stratégie d'autorisation sans l'appliquer, vous pouvez spécifier le champ iamEnforcementMode dans le bloc metadata. Cela vous permet de vérifier votre stratégie et de minimiser le risque de perturbation 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 (ou sélectionnez Appliquer les règles dans la console Google Cloud ) lorsque vous êtes prêt à commencer à appliquer les règles. Pour savoir comment auditer les cas de non-respect des règles de dry run avant d'activer l'application, consultez Auditer les cas de non-respect des règles de dry run dans les contrôles.

    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 stratégie 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. Vos modèles Model Armor peuvent se trouver dans le même projet que l'Agent Gateway et l'agent, ou dans un projet distinct, tel qu'un projet central de sécurité ou de gouvernance.

L'exemple suivant montre comment configurer une telle extension d'autorisation avec une stratégie d'autorisation pour Agent Gateway.

Console

Pour utiliser la console Google Cloud afin d'activer Model Armor pour Agent Gateway, procédez comme suit :

  1. Créez les modèles Model Armor requis.

  2. Consultez Configurer Agent Gateway pour activer Model Armor lors de la création d'Agent Gateway (en cochant la case Activer Model Armor). Les modèles Model Armor sont compatibles avec les modes Client-to-Agent et Agent-to-Anywhere.

  3. Lorsque vous utilisez Model Armor, vous devez accorder au compte de service Agent Gateway les autorisations requises pour pouvoir utiliser les modèles Model Armor. Le compte de service est au format service-PROJECT_NUMBER@gcp-sa-dep., où PROJECT_NUMBER est le numéro du projet dans lequel vous avez créé la passerelle.

    Vous devez effectuer cette étape même si la passerelle et les modèles se trouvent dans le même projet. Attribuez les rôles suivants :

    • Les rôles roles/modelarmor.calloutUser et roles/serviceusage.serviceUsageConsumer dans le projet contenant la passerelle.
    • Le rôle roles/modelarmor.user dans le projet contenant les modèles Model Armor.

    Vous devez utiliser la gcloud CLI pour effectuer cette étape.

    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.user
    

    Remplacez les éléments suivants :

    • GATEWAY_PROJECT_ID : ID du projet dans lequel vous avez créé la passerelle.
    • GATEWAY_PROJECT_NUMBER : numéro du projet dans lequel vous avez créé la passerelle.
    • MODEL_ARMOR_PROJECT_ID : ID du projet contenant le modèle Model Armor.

    Si vous utilisez la passerelle pour Agent Runtime, l'agent de service Agent Runtime a également besoin de ces autorisations, comme indiqué dans Acheminer le trafic Agent Runtime via Agent Gateway.

gcloud

  1. Créez les modèles Model Armor requis.

  2. Lorsque vous utilisez Model Armor, vous devez accorder au compte de service Agent Gateway les autorisations requises pour pouvoir utiliser les modèles Model Armor. Le compte de service est au format service-PROJECT_NUMBER@gcp-sa-dep., où PROJECT_NUMBER est le numéro du projet dans lequel vous avez créé la passerelle.

    Vous devez effectuer cette étape même si la passerelle et les modèles se trouvent dans le même projet. Attribuez les rôles suivants :

    • Les rôles roles/modelarmor.calloutUser et roles/serviceusage.serviceUsageConsumer dans le projet contenant la passerelle.
    • Le rôle roles/modelarmor.user dans le projet contenant le modèle Model Armor.
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.calloutUser
    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/serviceusage.serviceUsageConsumer
    gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
        --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep. \
        --role=roles/modelarmor.user
    

    Remplacez les éléments suivants :

    • GATEWAY_PROJECT_ID : ID du projet dans lequel vous avez créé la passerelle.
    • GATEWAY_PROJECT_NUMBER : numéro du projet dans lequel vous avez créé la passerelle.
    • MODEL_ARMOR_PROJECT_ID : ID du projet contenant le modèle Model Armor.
  3. Configurez l'extension d'autorisation pour qu'elle pointe vers Model Armor.

    1. Définissez l'extension dans un fichier YAML. Utilisez les exemples de valeurs fournis.

      cat >ma-content-authz-extension.yaml <<EOF
      name: my-ma-content-authz-ext
      service: modelarmor.LOCATION.rep.googleapis.com
      metadata:
        model_armor_settings: '[
          {
          "response_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID",
          "request_template_id": "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
          }
        ]'
      failOpen: false
      timeout: 1s
      EOF
      
    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-ma-content-authz-ext \
         --source=ma-content-authz-extension.yaml \
         --location=LOCATION
      
  4. Configurez une règle d'autorisation avec l'extension.

    1. Définissez une règle d'autorisation qui associe l'extension my-ma-content-authz-ext à une Agent Gateway.

      Agent vers n'importe quelle destination

      cat >ma-content-authz-policy.yaml <<EOF
      name: my-ma-content-authz-policy
      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/my-ma-content-authz-ext"
      httpRules:
        - to:
            operations: [ { "paths": [ { "prefix": "/" } ] } ]
          when: >
            request.headers['content-type'] == 'application/json' ||
            request.headers['content-type'].startsWith('text/')
      EOF
      

      Veuillez noter les points suivants :

      • La valeur de policyProfile est définie sur CONTENT_AUTHZ. Cela indique que le fournisseur de règles personnalisées traite le trafic des requêtes et des réponses, y compris le corps de la requête.

      • Le paramètre httpRules montre comment utiliser les attributs CEL pour créer des conditions qui correspondent au trafic spécifique que vous souhaitez transférer à Model Armor pour évaluation. Dans cet exemple, les règles correspondent à tout le trafic avec les types de contenu application/json ou text/. Nous vous recommandons d'utiliser de telles règles pour limiter l'évaluation de Model Armor au trafic pertinent. Cela vous permet d'acheminer le trafic des API LLM, MCP et A2A compatibles vers Model Armor tout en excluant le trafic interne, comme les appels gRPC des agents.

      Client vers agent

      cat >ma-content-authz-policy.yaml <<EOF
      name: my-ma-content-authz-policy
      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/my-ma-content-authz-ext"
      EOF
      

      La valeur de policyProfile est définie sur CONTENT_AUTHZ. Cela indique que le fournisseur de règles personnalisées traite le trafic des requêtes et des réponses, y compris le corps de la requête.

    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-ma-content-authz-policy \
        --source=ma-content-authz-policy.yaml \
        --location=LOCATION
      

Terraform

Pour configurer les extensions d'autorisation Model Armor et les règles CONTENT_AUTHZ de manière déclarative à l'aide du fournisseur google, définissez les liaisons IAM de l'agent de service, l'extension d'autorisation et la règle d'autorisation requises. Cette configuration s'applique que vos modèles Model Armor se trouvent dans le même projet que l'Agent Gateway et l'agent, ou dans un projet distinct. Si vos modèles Model Armor se trouvent dans un projet différent de celui qui contient l'agent ou l'Agent Gateway, et que vous utilisez VPC Service Controls, les deux projets doivent se trouver dans le même périmètre de service VPC Service Controls.

  1. Attribuez à l'agent de service Service Extensions les rôles requis dans le projet contenant l'Agent Gateway et dans le projet contenant vos modèles Model Armor. Vous devez effectuer cette étape même si la passerelle et les modèles se trouvent dans le même projet :

    resource "google_project_iam_member" "dep_ma_callout_user" {
      project = "PROJECT_ID"
      role    = "roles/modelarmor.calloutUser"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    
    resource "google_project_iam_member" "dep_service_usage_consumer" {
      project = "PROJECT_ID"
      role    = "roles/serviceusage.serviceUsageConsumer"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    
    resource "google_project_iam_member" "dep_ma_template_user" {
      project = "MODEL_ARMOR_PROJECT_ID"
      role    = "roles/modelarmor.user"
      member  = "serviceAccount:service-PROJECT_NUMBER@gcp-sa-dep."
    }
    

    Si vous utilisez la passerelle pour Agent Runtime, l'agent de service Agent Runtime doit également disposer des autorisations décrites dans Acheminer le trafic Agent Runtime via Agent Gateway.

  2. Définissez la ressource google_network_services_authz_extension pointant vers Model Armor :

    resource "google_network_services_authz_extension" "ma_content_authz_ext" {
      project   = "PROJECT_ID"
      location  = "LOCATION"
      name      = "my-ma-content-authz-ext"
      service   = "modelarmor.LOCATION.rep.googleapis.com"
      timeout   = "1s"
      fail_open = false
    
      metadata = {
        model_armor_settings = jsonencode([
          {
            response_template_id = "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
            request_template_id  = "projects/MODEL_ARMOR_PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID"
          }
        ])
      }
    
      depends_on = [
        google_project_iam_member.dep_ma_callout_user,
        google_project_iam_member.dep_service_usage_consumer,
        google_project_iam_member.dep_ma_template_user,
      ]
    }
    
  3. Associez l'extension à votre Agent Gateway à l'aide d'une ressource google_network_security_authz_policy :

    Agent vers n'importe quelle destination

    resource "google_network_security_authz_policy" "ma_content_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-ma-content-authz-policy"
      policy_profile = "CONTENT_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.ma_content_authz_ext.id
          ]
        }
      }
    
      http_rules {
        to {
          operations {
            paths {
              prefix = "/"
            }
          }
        }
        when = "request.headers['content-type'] == 'application/json' || request.headers['content-type'].startsWith('text/')"
      }
    }
    

    Client vers agent

    resource "google_network_security_authz_policy" "ma_content_authz_policy" {
      project        = "PROJECT_ID"
      location       = "LOCATION"
      name           = "my-ma-content-authz-policy"
      policy_profile = "CONTENT_AUTHZ"
      action         = "CUSTOM"
    
      target {
        resources = [
          "projects/PROJECT_ID/locations/LOCATION/agentGateways/AGENT_GATEWAY_NAME"
        ]
      }
    
      custom_provider {
        authz_extension {
          resources = [
            google_network_services_authz_extension.ma_content_authz_ext.id
          ]
        }
      }
    }
    

Remplacez les éléments suivants :

  • PROJECT_ID : ID du projet dans lequel vous avez créé l'Agent Gateway.

  • PROJECT_NUMBER : numéro du projet dans lequel vous avez créé l'Agent Gateway.

  • MODEL_ARMOR_PROJECT_ID : ID du projet contenant le modèle Model Armor. Il peut s'agir du même projet que PROJECT_ID ou d'un projet distinct. Si le modèle se trouve dans un projet différent de celui de l'agent ou de l'Agent Gateway, et que vous utilisez VPC Service Controls, les deux projets doivent se trouver dans le même périmètre de service.

  • LOCATION : région où se trouvent votre Agent Gateway et votre modèle Model Armor.

  • TEMPLATE_ID : ID du modèle Model Armor.

  • AGENT_GATEWAY_NAME : nom de la ressource 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 les décisions à des services personnalisés. Ces extensions personnalisées ne peuvent cibler que des noms de domaine complets (FQDN).

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 que l'appairage DNS est configuré 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 illustré dans l'exemple suivant. Cet exemple suppose que vous avez déployé un serveur dans votre réseau VPC qui implémente 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 stratégie 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 un nettoyage 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 d'autorisation de requêtes centralisé et Model Armor pour les garde-fous d'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 l'Agent Gateway.
    4. Créez la stratégie 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 où se trouvent 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 stratégie 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 stratégie d'autorisation CUSTOM avec le profil de stratégie CONTENT_AUTHZ. Cette règle doit pointer vers votre extension d'autorisation polyvalente. Cette approche permet d'activer 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 de filtrage des intents et de contraintes en langage naturel pour les stratégies d'autorisation au moteur de stratégies de gouvernance sémantique (semanticGovernancePolicyEngine).

Pour savoir comment provisionner le moteur de stratégies et créer la stratégie d'autorisation CONTENT_AUTHZ et la liaison d'extension d'autorisation requises sur votre passerelle, consultez Connecter le moteur de stratégies à 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 stratégies d'autorisation.

Vous pouvez restreindre l'accès en fonction des paramètres de méthode MCP, tels que les noms d'outils spécifiques. Cette section présente deux exemples, l'un pour une règle ALLOW et l'autre pour une règle 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 du protocole de base, mais interdit l'accès aux prompts et aux ressources.

    Lorsque vous écrivez une règle ALLOW, veillez à spécifier baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS afin que les RPC MCP non spécifiques à l'accès, comme l'initialisation, la journalisation, l'achèvement, les notifications et le ping, continuent de fonctionner. Dans le cas contraire, il est impossible d'établir une 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 méthodes prompts/ d'un serveur MCP derrière une Agent Gateway.

    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 stratégie 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 stratégie d'autorisation.
    • AUTH_POLICY_YAML_FILE_PATH : chemin d'accès au fichier YAML de la stratégie 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 passerelle :

    • Pour les passerelles Agent-to-Anywhere (sortie), vous pouvez configurer au maximum quatre règles d'autorisation par passerelle, quel que soit le profil de règle (REQUEST_AUTHZ ou CONTENT_AUTHZ).
    • Pour les passerelles client-agent (entrée), vous pouvez configurer au maximum une 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 :

Étapes suivantes

Atelier de programmation

Découvrez comment gouverner les charges de travail agentiques avec Agent Gateway sur Gemini Enterprise Agent Platform.

Guide

Découvrez comment afficher, mettre à jour, dissocier et supprimer des ressources Agent Gateway.

Guide

Découvrez comment surveiller Agent Gateway.

Dépannage

Découvrez comment résoudre les problèmes de connectivité d'Agent Gateway.