Delega l'autorizzazione con Service Extensions

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 Service Extensions.

Policy di autorizzazione ed estensioni

Le policy di autorizzazione consentono di applicare policy di controllo dell'accesso e governance centralizzate al traffico che passa attraverso gli endpoint pubblicati da Agent Gateway. Per gestire decisioni complesse di controllo dell'accesso, sicurezza dei contenuti e governance, Agent Gateway ti consente di configurare policy di autorizzazione con estensioni dell'autorizzazione che ti consentono di delegare le decisioni di autorizzazione e sicurezza dei contenuti ai motori di autorizzazione designati di tua scelta.

Un'estensione dell'autorizzazione intercetta le richieste che passano attraverso un deployment di Agent Gateway ed effettua una chiamata gRPC in tempo reale al servizio di autorizzazione designato. In questo modo, il servizio può ispezionare, modificare o bloccare il traffico prima che prosegua verso la destinazione. Puoi delegare l'autorizzazione a servizi Google Cloud come Identity-Aware Proxy, Model Armor e norme di governance semantica o a qualsiasi motore di autorizzazione personalizzato di tua scelta.

Le policy di autorizzazione utilizzano i profili delle policy per determinare il tipo di dati sul traffico inviati all'estensione dell'autorizzazione:

• Autorizzazione basata sulle richieste (REQUEST_AUTHZ): valuta le intestazioni delle richieste HTTP prima che venga elaborato qualsiasi payload dell'applicazione. Questo profilo viene utilizzato per la verifica dell'identità e controllo dell'accesso, ad esempio per delegare l'autorizzazione a Identity-Aware Proxy.
• Autorizzazione basata sui contenuti (CONTENT_AUTHZ): valuta i payload completi delle richieste e delle risposte HTTP. Questo profilo viene utilizzato per l'ispezione approfondita dei contenuti e la sicurezza dell'AI, ad esempio per delegare a Model Armor la sicurezza di prompt e risposte o alle norme di governance semantica l'applicazione dei vincoli del linguaggio naturale.

I motori di autorizzazione personalizzati possono utilizzare le estensioni REQUEST_AUTHZ o CONTENT_AUTHZ a seconda che ispezionino le intestazioni o i payload completi dell'applicazione.

Puoi configurare le estensioni dell'autorizzazione separatamente per le policy basate sulle richieste e quelle basate sui contenuti oppure combinarle entrambe su un gateway per una sicurezza completa. Per le configurazioni consigliate, consulta Configurazione consigliata per traffico in entrata e in uscita.

Per scoprire di più sulle policy di autorizzazione, sui profili delle policy e sui relativi casi d'uso, consulta la panoramica delle policy di autorizzazione.

Configurazione consigliata per traffico in entrata e in uscita

Per una sicurezza completa durante l'intero ciclo di vita dell'agente, consigliamo il seguente pattern di architettura multi-gateway:

• Gateway da client ad agente: i gateway da client ad agente (in entrata) supportano solo una singola policy CONTENT_AUTHZ. Ciò significa che non puoi utilizzare Model Armor e le norme di governance semantica insieme in entrata. Ti consigliamo vivamente di utilizzare una policy di Model Armor CONTENT_AUTHZ per proteggerti dagli attacchi di prompt injection. Tuttavia, se vuoi utilizzare un'estensione delle norme di governance semantica, devi assicurarti che Model Armor non sia configurato sul gateway. Altri tipi di estensioni dei servizi non sono supportati per i gateway in entrata.

• Gateway Agent-to-Anywhere: i gateway Agent-to-Anywhere (in uscita) supportano fino a quattro policy di autorizzazione. I gateway in uscita supportano sia i profili delle policy REQUEST_AUTHZ sia quelli delle policy CONTENT_AUTHZ e puoi configurare più policy di ogni tipo entro questo limite.

  Ti consigliamo la seguente configurazione:

  • Una policy REQUEST_AUTHZ che delega a Identity-Aware Proxy (IAP) l'autorizzazione dell'identità dell'agente.
  • Una o più policy CONTENT_AUTHZ che delegano ulteriori decisioni a Model Armor o alle norme di governance semantica per proteggere dall'esposizione dei dati sensibili e applicare vincoli di linguaggio naturale alle chiamate allo strumento e alle risposte in uscita.

  Per saperne di più su come vengono valutate le policy, consulta Valutazione delle policy in uscita.

Questa topologia multi-gateway garantisce che Model Armor filtri i prompt in entrata, mentre IAP, Model Armor e le norme di governance semantica filtrano le risposte in uscita.

Valutazione delle policy in uscita

Quando su un gateway in uscita sono configurate più policy di autorizzazione, queste vengono valutate in sequenza in base al tipo di profilo della policy:

1. Policy REQUEST_AUTHZ (basate su intestazione): questi tipi di policy vengono valutati per primi. Ad esempio, un'estensione IAP controlla l'identità mTLS dell'agente chiamante e convalida le sue policy di autorizzazione IAM prima che i contenuti vengano elaborati. Se la richiesta non supera questo controllo, viene rifiutata immediatamente.
2. Policy CONTENT_AUTHZ (basate sui contenuti): questi tipi di policy vengono valutati successivamente. Se la richiesta supera il controllo basato sulle intestazioni, il payload viene trasmesso in streaming all'estensione dell'autorizzazione basata sui contenuti (ad esempio il Policy Engine delle norme di governance semantica) per l'ispezione approfondita dei contenuti e la valutazione della conformità.

Prima di iniziare

Prima di iniziare, assicurati di soddisfare i seguenti requisiti:

• Il deployment dell'Agent Gateway è stato eseguito. Consulta Configura Agent Gateway.

• Devi disporre dell'autorizzazione IAM networkservices.agentGateways.use sulla risorsa Agent Gateway di cui è stato eseguito il deployment per poter collegare le policy di autorizzazione al gateway.

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

Delega l'autorizzazione a IAP

Puoi configurare un'estensione dell'autorizzazione della richiesta per delegare a IAP le decisioni di accesso per le policy di autorizzazione.

I passaggi seguenti mostrano come configurare un'estensione dell'autorizzazione con una policy di autorizzazione per un'istanza Agent Gateway.

1. Prima di iniziare: disattiva l'applicazione del vincolo della policy dell'organizzazione gestita Disabilita l'associazione della policy di accesso alla risorsa (constraints/iam.managed.disableAccessPolicyBindings). Per impostazione predefinita, questo vincolo booleano è abilitato per le nuove organizzazioni e impedisce di associare una policy di accesso unificato IAM a una risorsa. Per saperne di più, consulta Aggiornamento delle policy con regole booleane.

2. Crea le policy IAM in uscita richieste per gli agenti e gli strumenti. Per saperne di più, consulta Crea policy dell'agente IAM.

3. Consulta Configura Agent Gateway in modalità Agent-to-Anywhere (in uscita) per abilitare IAP durante la creazione di Agent Gateway (utilizzando il parametro Autorizzazione di accesso).

4. Configura un'estensione dell'autorizzazione in modo che rimandi a IAP.

   1. Definisci l'estensione in un file YAML. Utilizza i valori di esempio forniti. Se vuoi eseguire il deployment dell'estensione in modalità dry run solo controllo per testare la policy di autorizzazione senza applicarla, puoi specificare il campo iamEnforcementMode all'interno del blocco 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
      

      Se vuoi eseguire il deployment dell'estensione in modalità dry run solo controllo per testare la policy di autorizzazione senza applicarla, puoi specificare il campo iamEnforcementMode all'interno del blocco metadata. 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: false
      timeout: 1s
      metadata:
        iapPolicyVersion: "V2"
        iamEnforcementMode: "DRY_RUN"
      EOF
      

      Rimuovi il campo iamEnforcementMode: "DRY_RUN" dal blocco metadata (o seleziona Applica norme relative all'applicazione delle norme nella console Google Cloud ) quando è tutto pronto per iniziare ad applicare le norme relative all'applicazione delle norme. Per istruzioni su come controllare le violazioni della policy dry run prima di attivare l'applicazione, consulta Controlla le violazioni della policy dry run nei controlli.

      Nota: ti consigliamo vivamente di utilizzare Unified Access Policy (iapPolicyVersion: "V2") per controllo dell'accesso avanzato, espressivo e granulare. Per sostituire una policy di autorizzazione precedente (iapPolicyVersion: "V1") su un gateway esistente, vai alla UI delle policy e ridefinisci manualmente le regole nella scheda UAP. Per saperne di più, consulta Crea policy degli agenti IAM.

   2. Importa l'estensione dell'autorizzazione. Utilizza il comando gcloud service-extensions authz-extensions import con i seguenti valori di esempio.

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

5. Nello stesso progetto, configura una policy di autorizzazione che delega la decisione all'estensione.

   1. Definisci una policy di autorizzazione che associa l'estensione my-iap-request-authz-ext al 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"
      EOF
      

      Sostituisci PROJECT_ID con l'ID progetto.

   2. Importa la policy di autorizzazione nel progetto. Utilizza il comando gcloud network-security authz-policies import con i seguenti valori di esempio.

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

Delega l'autorizzazione a Model Armor

Puoi configurare un'estensione dell'autorizzazione per delegare le decisioni sulla sicurezza dei contenuti per le policy di autorizzazione a Model Armor. I tuoi template di Model Armor possono risiedere nello stesso progetto di Agent Gateway e dell'agente o in un progetto separato, ad esempio un progetto di sicurezza o governance centrale.

Nota: se i template di Model Armor si trovano in un progetto diverso da quello che contiene l'agente o l'Agent Gateway e utilizzi i Controlli di servizio VPC, entrambi i progetti devono trovarsi nello stesso perimetro di servizio dei Controlli di servizio VPC.

L'esempio seguente mostra come configurare un'estensione dell'autorizzazione di questo tipo con una policy di autorizzazione per Agent Gateway.

Console

Per utilizzare la console Google Cloud per attivare Model Armor per Agent Gateway, segui questi passaggi:

1. Crea i template Model Armor richiesti.

2. Consulta Configura Agent Gateway per attivare Model Armor durante la creazione di Agent Gateway (utilizzando la casella di controllo Attiva Model Armor). I template di Model Armor sono supportati sia in modalità Client-to-Agent che Agent-to-Anywhere.

3. Quando utilizzi Model Armor, devi concedere al account di servizio Agent Gateway le autorizzazioni necessarie per poter utilizzare i template di Model Armor. Il account di servizio ha il formato service-PROJECT_NUMBER@gcp-sa-dep., dove PROJECT_NUMBER è il numero del progetto in cui hai creato il gateway.

   Devi completare questo passaggio anche se sia il gateway sia i template si trovano nello stesso progetto. Concedi i seguenti ruoli:

   • I ruoli roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer nel progetto che contiene il gateway.
   • Il ruolo roles/modelarmor.user nel progetto che contiene i template di Model Armor.

   Per completare questo passaggio, dovrai utilizzare gcloud CLI.

   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
   

   Sostituisci quanto segue:

   • GATEWAY_PROJECT_ID: l'ID progetto in cui hai creato il gateway.
   • GATEWAY_PROJECT_NUMBER: il numero del progetto in cui hai creato il gateway.
   • MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il template di Model Armor.

   Se utilizzi il gateway per Agent Runtime, anche l'agente di servizio Agent Runtime richiede queste autorizzazioni, come documentato in Instrada il traffico di Agent Runtime tramite Agent Gateway.

gcloud

1. Crea i template Model Armor richiesti.

2. Quando utilizzi Model Armor, devi concedere al account di servizio Agent Gateway le autorizzazioni necessarie per poter utilizzare i template di Model Armor. Il account di servizio ha il formato service-PROJECT_NUMBER@gcp-sa-dep., dove PROJECT_NUMBER è il numero del progetto in cui hai creato il gateway.

   Devi completare questo passaggio anche se sia il gateway sia i template si trovano nello stesso progetto. Concedi i seguenti ruoli:

   • I ruoli roles/modelarmor.calloutUser e roles/serviceusage.serviceUsageConsumer nel progetto che contiene il gateway.
   • Il ruolo roles/modelarmor.user nel progetto che contiene il template di 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
   

   Sostituisci quanto segue:

   • GATEWAY_PROJECT_ID: l'ID progetto in cui hai creato il gateway.
   • GATEWAY_PROJECT_NUMBER: il numero del progetto in cui hai creato il gateway.
   • MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il template di Model Armor.

3. Configura l'estensione dell'autorizzazione in modo che punti a Model Armor.

   1. 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: false
      timeout: 1s
      EOF
      

   2. Importa l'estensione dell'autorizzazione. Utilizza il comando gcloud service-extensions authz-extensions import con i seguenti valori di esempio.

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

4. Configura una policy di autorizzazione con l'estensione.

   1. Definisci una policy di autorizzazione che associa l'estensione my-ma-content-authz-ext a 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/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
      

      Tieni presente quanto segue:

      • Il valore di policyProfile è impostato su CONTENT_AUTHZ. Ciò indica che il provider di policy personalizzate elabora il traffico di richieste e risposte, incluso il corpo della richiesta.

      • Il parametro httpRules mostra come utilizzare gli attributi 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 contenuti application/json o text/. Ti consigliamo di utilizzare queste regole per limitare la valutazione di Model Armor al traffico pertinente. In questo modo puoi instradare il traffico supportato delle API LLM, MCP e A2A verso Model Armor, escludendo il traffico interno come le chiamate gRPC dell'agente.

      Da client ad agente

      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
      

      Il valore di policyProfile è impostato su CONTENT_AUTHZ. Ciò indica che il provider di policy personalizzate elabora il traffico di richieste e risposte, incluso il corpo della richiesta.

   2. Importa la policy di autorizzazione nel progetto. Utilizza il comando gcloud network-security authz-policies import con i seguenti valori di esempio.

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

Terraform

Per configurare le estensioni di autorizzazione di Model Armor e le policy CONTENT_AUTHZ in modo dichiarativo utilizzando il provider google, definisci le associazioni IAM dell'agente di servizio, l'estensione dell'autorizzazione e la policy di autorizzazione richieste. Questa configurazione si applica indipendentemente dal fatto che i template di Model Armor si trovino nello stesso progetto dell'Agent Gateway e dell'agente o in un progetto separato. Se i tuoi template Model Armor si trovano in un progetto diverso da quello che contiene l'agente o l'Agent Gateway e utilizzi i Controlli di servizio VPC, entrambi i progetti devono trovarsi nello stesso perimetro di servizio dei Controlli di servizio VPC.

1. Concedi all'agente di servizio Service Extensions i ruoli richiesti nel progetto che contiene l'Agent Gateway e nel progetto che contiene i template di Model Armor. Devi completare questo passaggio anche se sia il gateway che i template si trovano nello stesso progetto:

   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."
   }
   

   Se utilizzi il gateway per Agent Runtime, anche l'agente di servizio Agent Runtime richiede le autorizzazioni documentate in Instrada il traffico di Agent Runtime tramite Agent Gateway.

2. Definisci la risorsa google_network_services_authz_extension che punta a 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. Collega l'estensione all'Agent Gateway con una risorsa google_network_security_authz_policy:

   Da agente a ovunque

   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/')"
     }
   }
   

   Da client ad agente

   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
         ]
       }
     }
   }
   

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto in cui hai creato l'Agent Gateway.

• PROJECT_NUMBER: il numero del progetto in cui hai creato l'Agent Gateway.

• MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il template Model Armor. Può trattarsi dello stesso progetto di PROJECT_ID o di un progetto separato. Se il template si trova in un progetto diverso da quello dell'agente o di Agent Gateway e utilizzi i Controlli di servizio VPC, entrambi i progetti devono trovarsi nello stesso perimetro di servizio.

• LOCATION: la regione in cui si trovano Agent Gateway e il template di Model Armor.

• TEMPLATE_ID: l'ID del template Model Armor.

• AGENT_GATEWAY_NAME: il nome della risorsa Agent Gateway.

Delega l'autorizzazione alle estensioni di autorizzazione personalizzate

Puoi configurare estensioni dell'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 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 tua rete VPC.

1. Per configurare un'estensione dell'autorizzazione con una policy di autorizzazione per un FQDN specifico, ad esempio mycustomauthz.internal.net, specificalo come valore per service nel file YAML dell'estensione, come mostrato nell'esempio seguente. Questo esempio presuppone che tu abbia eseguito il deployment di un server nella tua rete VPC che implementa il protocollo ext_proc in modalità di elaborazione del corpo FULL_DUPLEX_STREAMED.

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

2. Crea l'estensione dell'autorizzazione in modo che rimandi al servizio personalizzato.

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

3. Dopo aver creato l'estensione, configura una policy di autorizzazione CUSTOM che delega le decisioni all'estensione dell'autorizzazione.

     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. Crea la policy di autorizzazione.

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

Tieni presente che quando un'estensione dell'autorizzazione è associata a una policy di autorizzazione utilizzando il profilo CONTENT_AUTHZ, come mostrato in questo esempio, il gateway richiama l'estensione per i payload di richiesta e risposta (intestazioni e corpi), consentendo l'ispezione approfondita dei contenuti, i guardrail dei prompt e la sanitizzazione dei dati per il traffico dell'agente. Per impostazione predefinita, le policy CONTENT_AUTHZ utilizzano il protocollo Envoy ext_proc in modalità FULL_DUPLEX_STREAMED per elaborare gli eventi del corpo.

Combina l'autorizzazione IAP con i guardrail di Model Armor

Per una sicurezza completa, ti consigliamo di configurare una policy di autorizzazione PERSONALIZZATA con un profilo della policy REQUEST_AUTHZ e un'altra policy di autorizzazione PERSONALIZZATA con un profilo della policy CONTENT_AUTHZ.

L'esempio seguente utilizza IAP come sistema di autorizzazione delle richieste centralizzato e Model Armor per i guardrail dell'AI. Come mostrato negli esempi precedenti, puoi sostituire ciascuno di questi con le estensioni di servizio per utilizzare le tue soluzioni personalizzate.

1. Configura un'estensione dell'autorizzazione REQUEST_AUTHZ che delega a IAP e una policy di autorizzazione che rimanda all'estensione.

   1. Definisci l'estensione dell'autorizzazione. Il campo iapPolicyVersion in metadata è obbligatorio.

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

   2. Crea l'estensione dell'autorizzazione.

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

      Sostituisci LOCATION con la regione dell'estensione.

   3. Configura la policy di autorizzazione REQUEST_AUTHZ che 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"
      EOF
      

      Sostituisci quanto segue:

      • PROJECT_ID: il tuo ID progetto.
      • LOCATION: la località delle risorse.
      • AGENT_GATEWAY_NAME: il nome dell'Agent Gateway.

   4. Crea la policy di autorizzazione.

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

2. Configura un'estensione dell'autorizzazione CONTENT_AUTHZ che delega a Model Armor e una policy di autorizzazione che punta all'estensione.

   1. 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: false
      timeout: 1s
      EOF
      

      Sostituisci quanto segue:

      • LOCATION: la regione in cui si trovano i template di Model Armor.
      • MODEL_ARMOR_PROJECT_ID: l'ID progetto contenente i template di Model Armor.
      • RESPONSE_TEMPLATE_ID: l'ID del template di risposta.
      • REQUEST_TEMPLATE_ID: l'ID del template di richiesta.

   2. Crea l'estensione dell'autorizzazione.

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

   3. Configura la policy di autorizzazione CONTENT_AUTHZ che 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"
      EOF
      

   4. Crea la policy di autorizzazione.

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

Quando un'estensione dell'autorizzazione è associata a un profilo CONTENT_AUTHZ, riceve tutti gli eventi ext_proc, incluse intestazioni della richiesta e della risposta, corpo e trailer. Se l'estensione dell'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 della policy CONTENT_AUTHZ. Questa policy deve fare riferimento alla tua estensione dell'autorizzazione versatile. Questo approccio consente entrambi i tipi di autorizzazione tramite un'unica estensione e una connessione ext_proc, il che può migliorare i profili di latenza.

Delega l'autorizzazione alle norme di governance semantica

Puoi configurare un'estensione dell'autorizzazione per delegare le decisioni relative al controllo degli intent e ai vincoli del linguaggio naturale per le policy di autorizzazione al motore delle norme di governance semantica (semanticGovernancePolicyEngine).

Per scoprire come eseguire il provisioning del Policy Engine e creare la policy di autorizzazione CONTENT_AUTHZ e l'associazione dell'estensione dell'autorizzazione richieste sul tuo gateway, consulta Connetti il Policy Engine ad Agent Gateway.

Autorizzazione basata sugli attributi del protocollo MCP

Nota: per le policy di autorizzazione, le condizioni basate sugli attributi del protocollo agentico sono supportate solo per il Model Context Protocol (MCP). Altri protocolli agentici non sono supportati.

Agent Gateway analizza il payload del protocollo MCP in una richiesta e rende gli attributi estratti disponibili 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.

1. Configura la policy di autorizzazione.

   Esempio di policy ALLOW

   Questo 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 specificare baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS in modo che le RPC MCP specifiche per l'accesso, come inizializzazione, logging, completamento, notifiche 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
   EOF
   

   Esempio di policy DENY

   Questo 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
   EOF
   

2. Crea la policy di autorizzazione.

   gcloud 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:

• Il numero massimo di policy di autorizzazione per gateway dipende dalla modalità del gateway:

  • Per i gateway Agent-to-Anywhere (in uscita), puoi configurare un massimo di quattro policy di autorizzazione per gateway, indipendentemente dal profilo della policy (REQUEST_AUTHZ o CONTENT_AUTHZ).
  • Per i gateway da client ad agente (in entrata), puoi configurare un massimo di una policy CONTENT_AUTHZ.

  Per saperne di più, consulta Configurazione consigliata per traffico in entrata e in uscita.

• Se utilizzi estensioni dell'autorizzazione personalizzate con il profilo CONTENT_AUTHZ, devono supportare il protocollo ext_proc e la modalità FULL_DUPLEX_STREAMED per gli eventi del corpo.

• Se configuri più policy di autorizzazione personalizzate che utilizzano lo stesso profilo, l'ordine di esecuzione non è garantito.

Inoltre, consulta le sezioni seguenti per ulteriori informazioni sulle limitazioni delle estensioni dell'autorizzazione:

• Per le limitazioni applicabili a tutte le estensioni, consulta Limitazioni delle estensioni.

• Per le limitazioni applicabili ai callout, consulta Limitazioni dei callout.

Passaggi successivi

Codelab

Codelab: gestisci i workload degli agenti con Agent Platform

Scopri come gestire i workload degli agenti con Agent Gateway su Gemini Enterprise Agent Platform.

Guida

Gestisci Agent Gateway

Scopri come visualizzare, aggiornare, disassociare ed eliminare le risorse Agent Gateway.

Guida

Monitora Agent Gateway

Scopri come monitorare Agent Gateway.

Risoluzione dei problemi

Risolvi i problemi di Agent Gateway

Scopri come risolvere i problemi di connettività di Agent Gateway.