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 governance e controllo dell'accesso centralizzati al traffico che passa attraverso gli endpoint pubblicati da Agent Gateway. Per gestire decisioni complesse in materia di controllo dell'accesso dell'accesso, sicurezza dei contenuti e governance, Agent Gateway ti consente di configurare policy di autorizzazione con estensioni di autorizzazione che ti consentono di delegare le decisioni in materia di autorizzazione e sicurezza dei contenuti ai motori di autorizzazione designati di tua scelta.

Un'estensione di 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 raggiunga la destinazione. Puoi delegare l'autorizzazione a Cloud de Confiance servizi come Identity-Aware Proxy, Model Armor e le norme di governance semantica oppure a qualsiasi motore di autorizzazione personalizzato di tua scelta.

Le policy di autorizzazione utilizzano i profili delle policy per determinare il tipo di dati di 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à econtrollo dell'accessoo, ad esempio per delegare l'autorizzazione a Identity-Aware Proxy.
• Autorizzazione basata sui contenuti (CONTENT_AUTHZ): valuta i payload completi di richieste e risposte HTTP. Questo profilo viene utilizzato per l'ispezione approfondita dei contenuti e la sicurezza dell'AI, ad esempio per la delega a Model Armor per la sicurezza di prompt e risposte o alle norme di governance semantica per l'applicazione di vincoli in 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 delle applicazioni.

Puoi configurare le estensioni di autorizzazione separatamente per le policy basate su richieste e su contenuti oppure combinarle in un gateway per una sicurezza completa. Per le configurazioni consigliate, consulta Configurazione consigliata di Ingress e Egress.

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

Configurazione in entrata e in uscita consigliata

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 un criterio CONTENT_AUTHZ. Ciò significa che non puoi utilizzare insieme le policy di Model Armor e di governance semantica in entrata. Ti consigliamo vivamente di utilizzare un criterio 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 di servizio 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 i profili delle norme REQUEST_AUTHZ e CONTENT_AUTHZ e puoi configurare più norme 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ù norme CONTENT_AUTHZ che delegano ulteriori decisioni a Model Armor o norme di governance semantica per proteggere dall'esposizione di dati sensibili e applicare vincoli in linguaggio naturale alle chiamate e alle risposte degli strumenti 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 policy 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. Norme REQUEST_AUTHZ (basate sull'intestazione): questi tipi di norme vengono valutati per primi. Ad esempio, un'estensione IAP controlla l'identità mTLS dell'agente chiamante e convalida le relative policy di autorizzazione IAM prima che venga elaborato qualsiasi contenuto. Se la richiesta non supera questo controllo, viene immediatamente rifiutata.
2. Norme CONTENT_AUTHZ (basate sui contenuti): questi tipi di norme vengono valutati successivamente. Se la richiesta supera il controllo basato sull'intestazione, il payload viene trasmesso in streaming all'estensione dell'autorizzazione basata sui contenuti (ad esempio il motore di 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:

• L'Agent Gateway viene implementato. Consulta Configura Agent Gateway.

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

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.

Delega l'autorizzazione a IAP

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

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

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

2. Crea i criteri di uscita IAM richiesti per gli agenti e gli strumenti. Per saperne di più, consulta Crea policy dell'agente IAM.

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

4. Configura un'estensione dell'autorizzazione in modo che punti 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 tua 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 quando vuoi iniziare ad applicare i criteri.

   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 tuo 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 di autorizzazione per delegare le decisioni sulla sicurezza dei contenuti per le policy di autorizzazione a Model Armor.

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

Delegare l'autorizzazione alle estensioni di autorizzazione personalizzate

Puoi configurare estensioni di autorizzazione personalizzate per delegare le decisioni a servizi personalizzati. Queste estensioni personalizzate possono essere indirizzate solo a nomi di dominio completi (FQDN).

Quando utilizzi 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 implementato 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 punti 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 CUSTOMpolicy di autorizzazione che 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: 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 norma di autorizzazione utilizzando il profilo CONTENT_AUTHZ, come illustrato in questo esempio, il gateway richiama l'estensione per i payload di richiesta e risposta (intestazioni e corpi), consentendo l'ispezione approfondita dei contenuti, le misure di protezione dei prompt e la sanitizzazione dei dati per il traffico dell'agente. Per impostazione predefinita, i criteri CONTENT_AUTHZ utilizzano il protocollo Envoy ext_proc in modalità FULL_DUPLEX_STREAMED per elaborare gli eventi del corpo.

Combina l'autorizzazione IAP con le misure di protezione di Model Armor

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

L'esempio seguente utilizza IAP come sistema di autorizzazione delle richieste centralizzato e Model Armor per le misure di protezione 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 punta 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 il criterio di autorizzazione REQUEST_AUTHZ che delega l'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 posizione delle risorse.
      • AGENT_GATEWAY_NAME: il nome di 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 di 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 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.

   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 l'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, inclusi intestazioni, corpo e trailer di richieste e risposte. Se la tua estensione dell'autorizzazione basata su ext_proc è in grado di gestire sia l'autorizzazione in fase di 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 puntare all'estensione dell'autorizzazione versatile. Questo approccio consente entrambi i tipi di autorizzazione tramite una singola estensione e una singola connessione ext_proc, il che può migliorare i profili di latenza.

Delegare l'autorizzazione alle policy di governance semantica

Puoi configurare un'estensione dell'autorizzazione per delegare le decisioni relative a intent-gating e vincoli in 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 l'associazione di criteri di autorizzazione ed estensione dell'autorizzazione CONTENT_AUTHZ richiesta sul gateway, consulta Connettere il Policy Engine all'Agent Gateway.

Autorizzazione basata sugli attributi del protocollo MCP

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 un criterio ALLOW e uno per DENY.

1. Configura la policy di autorizzazione.

   ALLOW esempio di norma

   Questo esempio consente l'accesso a un insieme specifico di strumenti sul server MCP e alle funzionalità di base del protocollo, ma non consente l'accesso a prompt e risorse.

   Quando scrivi una norma ALLOW, assicurati di specificare baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS in modo che le RPC MCP specifiche per il non 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
   

   DENY esempio di norma

   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 posizione 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 un criterio CONTENT_AUTHZ.

  Per saperne di più, consulta la sezione Configurazione consigliata di Ingress e Egress.

• Se utilizzi estensioni di 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 di 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