Utilizza questa pagina per scoprire come delegare l'autorizzazione per Agent Gateway a Identity-Aware Proxy, Model Armor e altri motori di autorizzazione personalizzati utilizzando le Service Extensions.
Le policy di autorizzazione consentono di applicare policy di controllo dell'accesso e governance centralizzate al traffico che passa attraverso l'endpoint pubblicato da Agent Gateway. Queste policy consentono di gestire il traffico controllando l'accesso in base alle identità mTLS, agli attributi di richiesta e risposta e persino di personalizzare in base agli attributi specifici del protocollo utilizzati (ad esempio, i server MCP).
Le policy di autorizzazione utilizzano i profili di policy per determinare il tipo di autorizzazione da eseguire. Puoi utilizzare una policy di autorizzazione basata sulla richiesta (REQUEST_AUTHZ) che si basa sulle informazioni nelle intestazioni delle richieste HTTP per consentire o negare il traffico. In alternativa, puoi utilizzare una policy di autorizzazione basata sui contenuti (CONTENT_AUTHZ) quando devi eseguire un'ispezione più approfondita dei payload dell'applicazione per consentire o negare il traffico.
Per scoprire di più sulle policy di autorizzazione, sui profili di policy e sui relativi casi d'uso, consulta la panoramica delle policy di autorizzazione.
Estensioni di autorizzazione
A volte, le decisioni di autorizzazione complesse non possono essere espresse facilmente utilizzando una policy di autorizzazione. Agent Gateway consente di configurare policy di autorizzazione con estensioni di autorizzazione per delegare le decisioni di autorizzazione a motori di autorizzazione personalizzati.
Un'estensione di autorizzazione consente di intercettare e valutare le richieste che passano attraverso un deployment di Agent Gateway. Esegue una chiamata gRPC in tempo reale a un servizio esterno gestito dall'utente, in modo che tu possa ispezionare, modificare o persino bloccare il traffico prima che raggiunga la destinazione.
L'estensione ispeziona i dati in base alla policy di autorizzazione configurata. Puoi configurare le estensioni di autorizzazione separatamente per le policy di autorizzazione basate sulla richiesta e sui contenuti oppure puoi utilizzarle entrambe per una sicurezza completa.
Prima di iniziare
Prima di iniziare, assicurati di soddisfare i seguenti requisiti:
Agent Gateway è stato sottoposto a deployment. Consulta Configurare Agent Gateway.
Devi disporre dell'autorizzazione IAM
agentGateway.usesulla risorsa Agent Gateway di cui è stato eseguito il deployment per poter collegare le policy di autorizzazione al gateway.
Configurare le policy di autorizzazione con le estensioni
Questa sezione mostra come configurare le policy di autorizzazione che delegano le decisioni di autorizzazione e sicurezza dei contenuti a Identity-Aware Proxy, Model Armor e altri servizi personalizzati.
Delegare l'autorizzazione a IAP
Puoi configurare un'estensione di autorizzazione della richiesta per delegare le decisioni di accesso per le policy di autorizzazione a IAP.
I seguenti passaggi mostrano come configurare un'estensione di autorizzazione con una policy di autorizzazione per un'istanza di Agent Gateway.
Crea le policy in uscita IAM richieste per gli agenti e gli strumenti. Per ulteriori informazioni, consulta Creare policy IAM per gli agenti.
-
IAP richiede che gli agenti siano registrati con la risorsa del registro degli agenti associata al gateway.
Configura un'estensione di autorizzazione in modo che punti a IAP.
Definisci l'estensione in un file YAML. Utilizza i valori di esempio forniti.
cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true timeout: 1s EOFSe vuoi eseguire il deployment dell'estensione in modalità di solo controllo dry run, per testare la policy di autorizzazione senza applicarla, puoi specificare il campo
DRY_RUN. In questo modo puoi verificare la policy e ridurre al minimo il rischio di interruzione del traffico a causa di errori di configurazione: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" EOFRimuovi il campo di metadati
DRY_RUNquando è tutto pronto per iniziare ad applicare le policy.Importa l'estensione di autorizzazione. Utilizza il
gcloud beta service-extensions authz-extensions importcomando con i seguenti valori di esempio.gcloud beta service-extensions authz-extensions import my-iap-request-authz-ext
--source=iap-request-authz-extension.yaml
--location=LOCATION
Nello stesso progetto, configura una policy di autorizzazione che delega la decisione all'estensione.
Definisci una policy di autorizzazione che associa l'estensione
my-iap-request-authz-extal gateway. Utilizza i valori di esempio forniti.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" EOFSostituisci
PROJECT_IDcon l' ID progetto.Importa la policy di autorizzazione nel progetto. Utilizza il
gcloud beta network-security authz-policies importcomando con i seguenti valori di esempio.gcloud beta network-security authz-policies import my-iap-request-authz-policy
--source=iap-request-authz-policy.yaml
--location=LOCATION
Delegare l'autorizzazione a Model Armor
Puoi configurare un'estensione di autorizzazione per delegare le decisioni di sicurezza dei contenuti per le policy di autorizzazione a Model Armor.
L'esempio seguente mostra come configurare un'estensione di autorizzazione di questo tipo con una policy di autorizzazione per Agent Gateway.
Console
Per utilizzare la Google Cloud console per abilitare Model Armor per Agent Gateway, segui questi passaggi:
Crea i modelli Model Armor richiesti.
Consulta Configurare Agent Gateway per abilitare Model Armor durante la creazione di Agent Gateway (utilizzando la casella di controllo Abilita Model Armor). I modelli Model Armor sono supportati sia in modalità Da client ad agente sia in modalità Da agente a ovunque.
Se i modelli Model Armor si trovano in un progetto diverso dal gateway, devi concedere manualmente i ruoli richiesti al account di servizio di Agent Gateway. Il account di servizio ha il formato:
service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, dove PROJECT_NUMBER è il numero di progetto del progetto in cui hai creato il gateway.Concedi i seguenti ruoli:
- I ruoli
roles/modelarmor.calloutUsereroles/serviceusage.serviceUsageConsumernel progetto che contiene il gateway. - Il ruolo
roles/modelarmor.usernel progetto che contiene i modelli Model Armor.
Per completare questo passaggio, devi utilizzare gcloud CLI.
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
Sostituisci quanto segue:
GATEWAY_PROJECT_ID: l'ID progetto del progetto in cui hai creato il gateway.GATEWAY_PROJECT_NUMBER: il numero di progetto del progetto in cui hai creato il gateway.MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il modello Model Armor.
Se utilizzi il gateway per Agent Runtime, anche il service agent Reasoning Engine richiede queste autorizzazioni, come descritto in Instradare il traffico di Agent Runtime tramite Agent Gateway.
- I ruoli
gcloud
Crea i modelli Model Armor richiesti.
Se i modelli Model Armor si trovano in un progetto diverso dal gateway, devi concedere manualmente i ruoli richiesti al account di servizio di Agent Gateway. Il account di servizio ha il formato:
service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, dove PROJECT_NUMBER è il numero di progetto del progetto in cui hai creato il gateway.Concedi i seguenti ruoli:
- I ruoli
roles/modelarmor.calloutUsereroles/serviceusage.serviceUsageConsumernel progetto che contiene il gateway. - Il ruolo
roles/modelarmor.usernel progetto che contiene il modello 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
Sostituisci quanto segue:
GATEWAY_PROJECT_ID: l'ID progetto del progetto in cui hai creato il gateway.GATEWAY_PROJECT_NUMBER: il numero di progetto del progetto in cui hai creato il gateway.MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il modello Model Armor.
- I ruoli
Configura l'estensione di autorizzazione in modo che punti a Model Armor.
Definisci l'estensione in un file YAML. Utilizza i valori di esempio forniti.
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 EOFImporta l'estensione di autorizzazione. Utilizza il
gcloud beta service-extensions authz-extensions importcomando con i seguenti valori di esempio.gcloud beta service-extensions authz-extensions import my-ma-content-authz-ext \ --source=ma-content-authz-extension.yaml \ --location=LOCATION
Configura una policy di autorizzazione con l'estensione.
Definisci una policy di autorizzazione che associa l'estensione
my-ma-content-authz-exta un Agent Gateway.Da agente a ovunque
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/') EOFTieni presente quanto segue:
Il valore di
policyProfileè impostato suCONTENT_AUTHZ. Ciò indica che il provider di policy personalizzate elabora il traffico di richiesta e risposta, incluso il corpo della richiesta.Il parametro
httpRulesmostra come utilizzare CEL CEL per creare condizioni che corrispondono al traffico specifico che vuoi inoltrare a Model Armor per la valutazione. In questo esempio, le regole corrispondono a tutto il traffico con tipi di contenutiapplication/jsonotext/. Ti consigliamo di utilizzare queste regole per limitare la valutazione di Model Armor al traffico pertinente. In questo modo puoi instradare il traffico delle API LLM, MCP e A2A supportate a Model Armor, escludendo al contempo il traffico interno, ad esempio le chiamate gRPC degli agenti.
Da client ad agente
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" EOFIl valore di
policyProfileè impostato suCONTENT_AUTHZ. Ciò indica che il provider di policy personalizzate elabora il traffico di richiesta e risposta, incluso il corpo della richiesta.Importa la policy di autorizzazione nel progetto. Utilizza il
gcloud beta network-security authz-policies importcomando con i seguenti valori di esempio.gcloud beta network-security authz-policies import my-ma-content-authz-policy \ --source=ma-content-authz-policy.yaml \ --location=LOCATION
Delegare l'autorizzazione a estensioni di autorizzazione personalizzate
Puoi configurare estensioni di autorizzazione personalizzate per delegare le decisioni a servizi personalizzati. Queste estensioni personalizzate possono avere come target solo nomi di dominio completi (FQDN).
Quando utilizzi i target FQDN, l'estensione utilizza il protocollo HTTP2 con la crittografia TLS per comunicare con gli endpoint sulla porta 443. Tuttavia, l'estensione non convalida il certificato del server. Pertanto, per una maggiore sicurezza, devi assicurarti che gli endpoint risolti si trovino all'interno della rete VPC. Assicurati inoltre di aver configurato il peering DNS tra il progetto Agent Gateway e la rete VPC.
Per configurare un'estensione di autorizzazione con una policy di autorizzazione per un FQDN specifico, ad esempio
mycustomauthz.internal.net, specificalo come valore diservicenel file YAML dell'estensione, come mostrato nell'esempio seguente. Questo esempio presuppone che tu abbia eseguito il deployment di un server nella rete VPC che implementa il protocolloext_authz.cat >custom-authz-extension.yaml <<EOF name: my-custom-authz-ext service: mycustomauthz.internal.net failOpen: true timeout: 1s wireFormat: EXT_AUTHZ_GRPC EOFCrea l'estensione di autorizzazione in modo che punti al servizio personalizzato.
gcloud beta service-extensions authz-extensions import custom-authz-extension
--source=custom-authz-extension.yaml
--location=LOCATIONDopo aver creato l'estensione, configura una policy di autorizzazione
CUSTOMche delega le decisioni all'estensione di autorizzazione.$ 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 EOFCrea la policy di autorizzazione.
gcloud beta network-security authz-policies import authz-policy-with-extension \ --source=authz-policy.yaml \ --location=LOCATION
Tieni presente che quando un'estensione di autorizzazione è associata a una policy di autorizzazione utilizzando il profilo REQUEST_AUTHZ, come illustrato in questo esempio, il gateway richiama l'estensione solo quando arrivano le intestazioni delle richieste. Il corpo della richiesta, le intestazioni delle risposte e il corpo delle risposte non sono visibili all'estensione di autorizzazione.
Combinare l'autorizzazione IAP con le barriere di protezione di Model Armor
Per una sicurezza completa, ti consigliamo di configurare una policy di autorizzazione CUSTOM con un profilo di policy REQUEST_AUTHZ e un'altra policy di autorizzazione CUSTOM con un profilo di policy CONTENT_AUTHZ.
L'esempio seguente utilizza IAP come sistema di autorizzazione delle richieste centralizzato e Model Armor per le barriere di protezione AI. Come mostrato negli esempi precedenti, puoi sostituire ciascuno di questi con le estensioni di servizio per utilizzare le tue soluzioni personalizzate.
Configura un'estensione di autorizzazione
REQUEST_AUTHZche delega a IAP e una policy di autorizzazione che punta all'estensione.Definisci l'estensione di autorizzazione.
$ cat >iap-extension.yaml <<EOF name: iap-extension service: iap.googleapis.com failOpen: true timeout: 1s EOFCrea l'estensione di autorizzazione.
gcloud beta service-extensions authz-extensions import iap-extension \ --source=iap-extension.yaml \ --location=LOCATION
Sostituisci
LOCATIONcon la regione dell'estensione.Configura la policy di autorizzazione
REQUEST_AUTHZche delega all'estensione.$ 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" EOFSostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.LOCATION: la località delle risorse.AGENT_GATEWAY_NAME: il nome di Agent Gateway.
Crea la policy di autorizzazione.
gcloud beta network-security authz-policies import authz-iap \ --source=authz-policy-request-authz.yaml \ --location=LOCATION
Configura un'estensione di autorizzazione
CONTENT_AUTHZche delega a Model Armor e una policy di autorizzazione che punta all'estensione.Definisci l'estensione.
$ 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 EOFSostituisci quanto segue:
LOCATION: la regione in cui risiedono i modelli Model Armor.MODEL_ARMOR_PROJECT_ID: l'ID progetto contenente i modelli Model Armor.RESPONSE_TEMPLATE_ID: l'ID del modello di risposta.REQUEST_TEMPLATE_ID: l'ID del modello di richiesta.
Crea l'estensione di autorizzazione.
gcloud beta service-extensions authz-extensions import ma-extension \ --source=ma-extension-file.yaml \ --location=LOCATION
Configura la policy di autorizzazione
CONTENT_AUTHZche delega all'estensione.$ 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" EOFCrea la policy di autorizzazione.
gcloud beta network-security authz-policies import ma-authz-policy \ --source=authz-policy-content-authz.yaml \ --location=LOCATION
Quando un'estensione di autorizzazione è associata a un profilo CONTENT_AUTHZ, riceve tutti gli eventi ext_proc, incluse le intestazioni, il corpo e i trailer di richiesta e risposta. Se l'estensione di autorizzazione basata su ext_proc è in grado di gestire sia l'autorizzazione al momento della richiesta sia l'autorizzazione basata sui contenuti, ti consigliamo di configurare una singola policy di autorizzazione CUSTOM con il profilo di policy CONTENT_AUTHZ. Questa policy deve puntare all'estensione di autorizzazione versatile. Questo approccio consente entrambi i tipi di autorizzazione tramite una singola estensione e una connessione ext_proc, il che può migliorare la latenza rispetto all'utilizzo di estensioni separate per i profili REQUEST_AUTHZ e CONTENT_AUTHZ.
Autorizzazione basata sugli attributi del protocollo MCP
Agent Gateway analizza il payload del protocollo MCP in una richiesta e rende disponibili gli attributi estratti per le policy di autorizzazione.
Puoi limitare l'accesso in base ai parametri del metodo MCP, ad esempio i nomi di strumenti specifici. Questa sezione mostra due esempi, uno per una policy ALLOW e uno per DENY.
Configura la policy di autorizzazione.
Esempio di policy
ALLOWQuesto esempio consente l'accesso a un insieme specifico di strumenti sul server MCP e alle funzionalità del protocollo di base, ma non consente l'accesso a prompt e risorse.
Quando scrivi una policy
ALLOW, assicurati di specificarebaseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODSin modo che gli RPC MCP non specifici per l'accesso, come initialize, logging, completion, notifications e ping, continuino a funzionare. In caso contrario, non sarà possibile stabilire una sessione 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 EOFEsempio di policy
DENYQuesto esempio non consente l'accesso a tutti i prompt/ metodi a un server MCP dietro un 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 EOFCrea la policy di autorizzazione.
gcloud beta network-security authz-policies import AUTHZ_POLICY_NAME \ --source=AUTH_POLICY_YAML_FILE_PATH \ --location=LOCATION
Sostituisci quanto segue:
AUTHZ_POLICY_NAME: il nome della policy di autorizzazione.AUTH_POLICY_YAML_FILE_PATH: il percorso del file YAML della policy di autorizzazione.LOCATION: la località delle risorse.
Limitazioni
Quando utilizzi le policy di autorizzazione, si applicano le seguenti limitazioni:
- Puoi configurare un massimo di quattro policy di autorizzazione personalizzate per Agent Gateway, indipendentemente dal profilo della policy.
- Se utilizzi estensioni di autorizzazione personalizzate con il profilo
CONTENT_AUTHZ, queste devono supportare il protocolloext_proce la modalitàFULL_DUPLEX_STREAMEDper gli eventi del corpo. - Se configuri più policy di autorizzazione personalizzate che utilizzano lo stesso profilo, l'ordine di esecuzione non è garantito.
Inoltre, per ulteriori informazioni sulle limitazioni delle estensioni di autorizzazione, consulta le sezioni seguenti:
Per le limitazioni applicabili a tutte le estensioni, consulta Limitazioni delle estensioni.
Per le limitazioni applicabili ai callout, consulta Limitazioni dei callout.