Cette page explique comment déléguer l'autorisation de la passerelle d'agent à Identity-Aware Proxy, Model Armor et d'autres moteurs d'autorisation personnalisés à l'aide des Service Extensions.
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 la passerelle d'agent. 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és (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 effectuer une inspection plus approfondie des 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 la 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. La passerelle d'agent 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 de passerelle d'agent. Elle effectue un appel gRPC en temps réel à un service externe que vous gérez, afin que vous puissiez inspecter, modifier ou même bloquer le trafic avant qu'il n'atteigne sa destination.
L'extension inspecte les données en fonction de la règle d'autorisation configurée authorization policy. Vous pouvez configurer des 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 la section Configurer la passerelle d'agent.
Vous devez disposer de l'autorisation IAM
agentGateway.usesur la ressource de passerelle d'agent 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 de requête pour déléguer les décisions d'accès des règles d'autorisation à IAP.
Les étapes suivantes expliquent comment configurer une extension d'autorisation avec une règle d'autorisation pour une instance de passerelle d'agent.
Créez les règles de sortie IAM requises pour vos agents et outils. Pour en savoir plus, consultez la section Créer des règles d'agent IAM.
-
IAP exige que vos agents soient enregistrés auprès de la ressource de registre d'agent liée à la passerelle.
Configurez une extension d'autorisation pour qu'elle pointe vers IAP.
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 timeout: 1s EOFSi vous souhaitez déployer l'extension en mode de simulation 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 timeout: 1s metadata: iamEnforcementMode: "DRY_RUN" EOFSupprimez le champ de métadonnées
DRY_RUNlorsque vous êtes prêt à commencer à appliquer les règles.Importez l'extension d'autorisation. Utilisez la
gcloud beta service-extensions authz-extensions importcommande 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
Dans le même projet, configurez une règle d'autorisation qui délègue la décision à l'extension.
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" EOFRemplacez
PROJECT_IDpar l'ID de votre projet.Importez la règle d'autorisation dans le projet. Utilisez la
gcloud beta network-security authz-policies importcommande 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 des règles d'autorisation à Model Armor.
L'exemple suivant montre comment configurer une extension d'autorisation de ce type avec une règle d'autorisation pour la passerelle d'agent.
Console
Pour utiliser la Google Cloud console afin d'activer Model Armor pour la passerelle d'agent, procédez comme suit :
Créez les modèles Model Armor requis.
Consultez la section Configurer la passerelle d'agent pour activer Model Armor lors de la création de la passerelle d'agent (à l'aide de la case à cocher Activer Model Armor). Les modèles Model Armor sont compatibles avec les modes "Client vers agent" et "Agent vers n'importe quelle destination".
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 de la passerelle d'agent. Le compte de service est au format :
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.calloutUseretroles/serviceusage.serviceUsageConsumerdans le projet contenant la passerelle. - Le rôle
roles/modelarmor.userdans le projet contenant 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 l'environnement d'exécution d'agent, l'agent de service du moteur de raisonnement nécessite également ces autorisations, comme indiqué dans la section Acheminer le trafic de l'environnement d'exécution d'agent via la passerelle d'agent.
- Les rôles
gcloud
Créez les modèles Model Armor requis.
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 de la passerelle d'agent. Le compte de service est au format :
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.calloutUseretroles/serviceusage.serviceUsageConsumerdans le projet contenant la passerelle. - Le rôle
roles/modelarmor.userdans 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.
- Les rôles
Configurez l'extension d'autorisation pour qu'elle pointe vers Model Armor.
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 EOFImportez l'extension d'autorisation. Utilisez la
gcloud beta service-extensions authz-extensions importcommande 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
Configurez une règle d'autorisation avec l'extension.
Définissez une règle d'autorisation qui associe l'extension
my-ma-content-authz-extà une passerelle d'agent.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/gateways/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/') EOFVeuillez noter les points suivants :
La valeur de
policyProfileest définie surCONTENT_AUTHZ. Cela indique que le fournisseur de règles personnalisé traite le trafic de requête et de réponse, y compris le corps de la requête.Le paramètre
httpRulesmontre comment utiliser CEL attributs 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 contenuapplication/jsonoutext/. Nous vous recommandons d'utiliser ces règles pour limiter l'évaluation de Model Armor au trafic pertinent. Cela vous permet de router le trafic LLM API, MCP et A2A compatible vers Model Armor tout en excluant le trafic interne tel que les appels gRPC d'agent.
Client vers 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" EOFLa valeur de
policyProfileest définie surCONTENT_AUTHZ. Cela indique que le fournisseur de règles personnalisé traite le trafic de requête et de réponse, y compris le corps de la requête.Importez la règle d'autorisation dans le projet. Utilisez la
gcloud beta network-security authz-policies importcommande 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 à 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 FQDN, 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 de passerelle d'agent et votre réseau VPC.
Pour configurer une extension d'autorisation avec une règle d'autorisation pour un FQDN spécifique, tel que
mycustomauthz.internal.net, spécifiez-le comme valeur deservicedans 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 protocoleext_authz.cat >custom-authz-extension.yaml <<EOF name: my-custom-authz-ext service: mycustomauthz.internal.net failOpen: true timeout: 1s wireFormat: EXT_AUTHZ_GRPC EOFCré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
Une fois l'extension créée, configurez une règle d'autorisation
CUSTOMqui 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 EOFCré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 des 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 pour 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 CUSTOM avec un profil de règle REQUEST_AUTHZ et une autre règle d'autorisation CUSTOM avec un profil de règle CONTENT_AUTHZ.
L'exemple suivant utilise IAP comme système d'autorisation de requête centralisé et Model Armor pour les garde-fous d'IA. Comme indiqué dans les exemples précédents, vous pouvez remplacer chacun d'eux par des extensions de service pour utiliser vos propres solutions personnalisées.
Configurez une extension d'autorisation
REQUEST_AUTHZqui délègue à IAP et une règle d'autorisation qui pointe vers l'extension.Définissez l'extension d'autorisation.
cat >iap-extension.yaml <<EOF name: iap-extension service: iap.googleapis.com failOpen: true timeout: 1s EOFCréez l'extension d'autorisation.
gcloud beta service-extensions authz-extensions import iap-extension \ --source=iap-extension.yaml \ --location=LOCATION
Remplacez
LOCATIONpar la région de l'extension.Configurez la règle d'autorisation
REQUEST_AUTHZqui 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" EOFRemplacez les éléments suivants :
PROJECT_ID: ID de votre projetLOCATION: emplacement des ressourcesAGENT_GATEWAY_NAME: nom de la passerelle d'agent
Créez la règle d'autorisation.
gcloud beta network-security authz-policies import authz-iap \ --source=authz-policy-request-authz.yaml \ --location=LOCATION
Configurez une extension d'autorisation
CONTENT_AUTHZqui délègue à Model Armor et une règle d'autorisation qui pointe vers l'extension.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 EOFRemplacez les éléments suivants :
LOCATION: région où résident vos modèles Model ArmorMODEL_ARMOR_PROJECT_ID: ID du projet contenant les modèles Model ArmorRESPONSE_TEMPLATE_ID: ID du modèle de réponseREQUEST_TEMPLATE_ID: ID du modèle de requête
Créez l'extension d'autorisation.
gcloud beta service-extensions authz-extensions import ma-extension \ --source=ma-extension-file.yaml \ --location=LOCATION
Configurez la règle d'autorisation
CONTENT_AUTHZqui 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" EOFCré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 de requête et de réponse, le corps et les trailers. 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 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
La passerelle d'agent 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 limiter 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 une règle DENY.
Configurez la règle d'autorisation.
Exemple de règle
ALLOWCet 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écifierbaseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODSafin que les RPC MCP non spécifiques à l'accès, tels que l'initialisation, la journalisation, la finalisation, 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 EOFExemple de règle
DENYCet exemple interdit toutes les invites/ méthodes d'accès à 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 EOFCré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'autorisationAUTH_POLICY_YAML_FILE_PATH: chemin d'accès au fichier YAML de la règle d'autorisationLOCATION: emplacement des ressources
Limites
Les limites suivantes s'appliquent lorsque vous utilisez des règles d'autorisation :
- Vous pouvez configurer un maximum de 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 protocoleext_procet le modeFULL_DUPLEX_STREAMEDpour 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 les sections suivantes :
Pour connaître les limites applicables à toutes les extensions, consultez la section Limites des extensions.
Pour connaître les limites applicables aux callouts, consultez la section Limites des callouts.