Déléguer l'autorisation avec les 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.

Les règles d'autorisation vous permettent d'appliquer des règles de contrôle des accès et de gouvernance centralisées au trafic transitant par le point de terminaison publié par Agent Gateway. Ces règles vous permettent de gérer le trafic en contrôlant l'accès en fonction des identités mTLS, des attributs de requête et de réponse, et même de personnaliser en fonction des attributs spécifiques au protocole utilisé (par exemple, les serveurs MCP).

Les règles d'autorisation utilisent des profils de règles pour déterminer le type d'autorisation à effectuer. Vous pouvez utiliser une règle d'autorisation basée sur les requêtes (REQUEST_AUTHZ) qui s'appuie sur les informations contenues dans les en-têtes de requête HTTP pour autoriser ou refuser le trafic. Vous pouvez également utiliser une règle d'autorisation basée sur le contenu (CONTENT_AUTHZ) lorsque vous devez inspecter plus en détail les charges utiles de votre application pour autoriser ou refuser le trafic.

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.

Extensions d'autorisation

Parfois, les décisions d'autorisation complexes ne peuvent pas être facilement exprimées à l'aide d'une règle d'autorisation. Agent Gateway vous permet de configurer des règles d'autorisation avec des extensions d'autorisation pour déléguer les décisions d'autorisation à des moteurs d'autorisation personnalisés.

Une extension d'autorisation vous permet d'intercepter et d'évaluer les requêtes qui transitent par un déploiement Agent Gateway. Il effectue un appel gRPC en temps réel à un service externe que vous gérez, ce qui vous permet d'inspecter, de modifier ou même de bloquer le trafic avant qu'il ne poursuive sa route vers sa destination.

L'extension inspecte les données en fonction de la règle d'autorisation configurée. Vous pouvez configurer les extensions d'autorisation séparément pour les règles d'autorisation basées sur les requêtes et celles basées sur le contenu, ou vous pouvez utiliser les deux pour une sécurité complète.

Avant de commencer

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

  • La passerelle d'agent est déployée. Consultez Configurer Agent Gateway.

  • Vous devez disposer de l'autorisation IAM agentGateway.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 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.

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

Console

Pour activer IAP pour Agent Gateway à l'aide de la console Google Cloud , procédez comme suit :

  1. 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.

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

    IAP exige que vos agents soient enregistrés auprès de la ressource Agent Registry liée à la passerelle.

gcloud

  1. Configurez l'extension d'autorisation pour qu'elle pointe vers IAP.

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

      cat >iap-request-authz-extension.yaml <<EOF
name: my-iap-request-authz-ext
service: iap.googleapis.com
failOpen: true
EOF

      Si vous souhaitez déployer l'extension en mode audit uniquement pour tester la règle d'autorisation sans l'appliquer, vous pouvez spécifier le champ DRY_RUN. 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: true
metadata: '
  iamEnforcementMode: DRY_RUN
'
EOF

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

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

  2. 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-authz-request-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 beta network-security authz-policies import avec les exemples de valeurs suivants.

      gcloud beta 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.

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. Si vos modèles Model Armor se trouvent dans un projet différent de celui de la passerelle, vous devez accorder manuellement les rôles requis au compte de service Agent Gateway. Le compte de service se présente sous la forme suivante : service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, où PROJECT_NUMBER est le numéro du projet dans lequel vous avez créé la passerelle.

    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 qui contient les modèles Model Armor.

    Vous devrez utiliser gcloud CLI pour effectuer cette étape.

    gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --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 Reasoning Engine nécessite également ces autorisations, comme indiqué dans Router le trafic Agent Runtime via Agent Gateway.

gcloud

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

  2. Si vos modèles Model Armor se trouvent dans un projet différent de celui de la passerelle, vous devez accorder manuellement les rôles requis au compte de service Agent Gateway. Le compte de service se présente sous la forme suivante : service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, où PROJECT_NUMBER est le numéro du projet dans lequel vous avez créé la passerelle.

    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.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding GATEWAY_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding MODEL_ARMOR_PROJECT_ID \
 --member=serviceAccount:service-GATEWAY_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
 --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: true
timeout: 1s
EOF

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

      gcloud beta 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 passerelle d'agent.

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

      Pour les règles d'autorisation de contenu, la valeur de policyProfile est définie sur CONTENT_AUTHZ. Cette valeur indique que le fournisseur de règles personnalisées traite le trafic de requêtes et de réponses, y compris le traitement du corps.

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

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

Déléguer l'autorisation aux 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.

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_authz.

    cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: true
wireFormat: EXT_AUTHZ_GRPC
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 CUSTOM règle d'autorisation 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: REQUEST_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 beta 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 REQUEST_AUTHZ, comme illustré dans cet exemple, la passerelle n'appelle l'extension que lorsque les en-têtes de requête arrivent. Le corps de la requête, les en-têtes de réponse et le corps de la réponse ne sont pas visibles par l'extension d'autorisation.

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.

      $ cat >iap-extension.yaml <<EOF
name: iap-extension
service: iap.googleapis.com
failOpen: true
EOF

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

      gcloud beta 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 de votre projet
      • LOCATION : emplacement des ressources.
      • AGENT_GATEWAY_NAME : nom de la passerelle d'agent.

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

      gcloud beta 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: true
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 beta 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 beta 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 les deux types d'autorisation via une seule extension et une seule connexion ext_proc, ce qui peut améliorer la latence par rapport à l'utilisation d'extensions distinctes pour les profils REQUEST_AUTHZ et CONTENT_AUTHZ.

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 règle 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, comme 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 beta 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 :

  • Vous pouvez configurer jusqu'à quatre règles d'autorisation personnalisées par passerelle d'agent, quel que soit le profil de règle.
  • 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

Guide

Découvrez comment surveiller Agent Gateway.