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.

Le policy di autorizzazione consentono di applicare criteri di controllo dell'accesso e governance centralizzati al traffico che passa attraverso l'endpoint pubblicato da Agent Gateway. Questi criteri ti 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).

I criteri di autorizzazione utilizzano i profili dei criteri per determinare il tipo di autorizzazione da eseguire. Puoi utilizzare un criterio di autorizzazione basato sulle richieste (REQUEST_AUTHZ) che si basa sulle informazioni contenute 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 delle policy e sui relativi casi d'uso, consulta la panoramica delle policy di autorizzazione.

Estensioni autorizzazione

A volte, le decisioni di autorizzazione complesse non possono essere espresse facilmente utilizzando una policy di autorizzazione. Agent Gateway ti 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 ti consente di intercettare e valutare le richieste che passano attraverso un deployment del gateway dell'agente. 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 esamina i dati in base al criterio di autorizzazione configurato. Puoi configurare le estensioni di autorizzazione separatamente per le policy di autorizzazione basate su richieste e su contenuti oppure puoi utilizzarle entrambe per una sicurezza completa.

Prima di iniziare

Prima di iniziare, assicurati di soddisfare i seguenti requisiti:

  • Il gateway dell'agente è stato implementato. Consulta Configura Agent Gateway.

  • Devi disporre dell'autorizzazione IAM agentGateway.use sulla risorsa gateway dell'agente 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.

Delega l'autorizzazione a IAP

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

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

Console

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

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

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

    IAP richiede che gli agenti siano registrati con la risorsa Agent Registry associata al gateway.

gcloud

  1. Configura l'estensione di autorizzazione in modo che punti a IAP.

    1. 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
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 DRY_RUN. 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: true
metadata: '
  iamEnforcementMode: DRY_RUN
'
EOF

    2. Importa l'estensione autorizzazione. Utilizza il comando gcloud beta service-extensions authz-extensions import 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

  2. Nello stesso progetto, configura un criterio di autorizzazione che delega la decisione all'estensione.

    1. Definisci una policy di autorizzazione che associa l'estensione my-iap-authz-request-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 beta network-security authz-policies import 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

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 di autorizzazione di questo tipo con una policy di autorizzazione per Agent Gateway.

Console

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

  1. Crea i template Model Armor richiesti.

  2. Consulta Configura 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à Client-to-Agent che Agent-to-Anywhere.

  3. Se i tuoi modelli Model Armor si trovano in un progetto diverso dal gateway, devi concedere manualmente i ruoli richiesti al account di servizio del gateway degli agenti. Il account di servizio ha il formato service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, dove PROJECT_NUMBER è il numero del progetto in cui hai creato il gateway.

    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 contenente i modelli 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.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 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 documentato in Instradare il traffico di Agent Runtime tramite Agent Gateway.

gcloud

  1. Crea i template Model Armor richiesti.

  2. Se i tuoi modelli Model Armor si trovano in un progetto diverso dal gateway, devi concedere manualmente i ruoli richiesti al account di servizio del gateway degli agenti. 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.calloutUser e roles/serviceusage.serviceUsageConsumer nel progetto che contiene il gateway.
    • Il ruolo roles/modelarmor.user nel progetto contenente 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 del progetto in cui hai creato il gateway.
    • MODEL_ARMOR_PROJECT_ID: l'ID progetto del progetto che contiene il modello Model Armor.

  3. Configura l'estensione di 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: true
timeout: 1s
EOF

    2. Importa l'estensione autorizzazione. Utilizza il comando gcloud beta service-extensions authz-extensions import 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

  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 gateway dell'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"
EOF

      Per le norme di autorizzazione dei contenuti, il valore di policyProfile è impostato su CONTENT_AUTHZ. Questo valore indica che il provider di policy personalizzate elabora il traffico di richieste e risposte, inclusa l'elaborazione del corpo.

    2. Importa la policy di autorizzazione nel progetto. Utilizza il comando gcloud beta network-security authz-policies import 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 essere indirizzate solo a 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 di 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_authz.

    cat >custom-authz-extension.yaml <<EOF
name: my-custom-authz-ext
service: mycustomauthz.internal.net
failOpen: true
wireFormat: EXT_AUTHZ_GRPC
EOF

  2. Crea 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=LOCATION

  3. Dopo aver creato l'estensione, configura un criterio di autorizzazione CUSTOM 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: REQUEST_AUTHZ
  action: CUSTOM
  customProvider:
  authzExtension:
    resources:
    - projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension
  EOF

  4. Crea 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 norma di autorizzazione che utilizza 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 della risposta e il corpo della risposta non sono visibili all'estensione di autorizzazione.

Combina l'autorizzazione IAP con le barriere protettive 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 di autorizzazione REQUEST_AUTHZ che delega a IAP e una policy di autorizzazione che punta all'estensione.

    1. Definisci l'estensione di autorizzazione.

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

    2. Crea l'estensione di autorizzazione.

      gcloud beta 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'accesso 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 posizione delle risorse.
      • AGENT_GATEWAY_NAME: il nome del gateway dell'agente.

    4. Crea la policy di autorizzazione.

      gcloud beta 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: true
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 di autorizzazione.

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

    3. Configura il criterio di autorizzazione CONTENT_AUTHZ che delega l'accesso 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 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 intestazioni di richieste e risposte, corpo e trailer. Se l'estensione di 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 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 norme 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.

    ALLOWEsempio di norma

    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 un criterio ALLOW, assicurati di specificare baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS in modo che le RPC MCP non 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

    DENYEsempio 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 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 posizione delle risorse.

Limitazioni

Quando utilizzi le policy di autorizzazione, si applicano le seguenti limitazioni:

  • Puoi configurare un massimo di quattro criteri di autorizzazione personalizzati per Agent Gateway, indipendentemente dal profilo dei criteri.
  • 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:

Passaggi successivi

Guida

Scopri come monitorare Agent Gateway.