Autorisierung mit Service Extensions delegieren

Auf dieser Seite erfahren Sie, wie Sie die Autorisierung für Agent Gateway mithilfe von Service Extensions an Identity-Aware Proxy, Model Armor und andere benutzerdefinierte Autorisierungs-Engines delegieren.

Autorisierungsrichtlinien und ‑erweiterungen

Mit Autorisierungsrichtlinien können Sie zentralisierte Zugriffssteuerungs- und Governance-Richtlinien für Traffic erzwingen, der über vom KI-Agenten-Gateway veröffentlichte Endpunkte geleitet wird. Für komplexe Entscheidungen in Bezug auf Zugriffssteuerung, Inhaltssicherheit und Governance können Sie mit Agent Gateway Autorisierungsrichtlinien mit Autorisierungserweiterungen konfigurieren. So können Sie Autorisierungs- und Inhaltssicherheitsentscheidungen an ausgewählte Autorisierungs-Engines Ihrer Wahl delegieren.

Eine Autorisierungserweiterung fängt Anfragen ab, die über eine Agent Gateway-Bereitstellung laufen, und sendet einen gRPC-Aufruf in Echtzeit an den angegebenen Autorisierungsdienst. So kann der Dienst den Traffic prüfen, ändern oder blockieren, bevor er an sein Ziel weitergeleitet wird. Sie können die Autorisierung an Google Cloud -Dienste wie Identity-Aware Proxy, Model Armor und semantische Governance-Richtlinien oder an eine beliebige benutzerdefinierte Autorisierungs-Engine Ihrer Wahl delegieren.

Autorisierungsrichtlinien verwenden Richtlinienprofile, um den Typ der Traffic-Daten zu bestimmen, die an die Autorisierungserweiterung gesendet werden:

  • Anfragebasierte Autorisierung (REQUEST_AUTHZ): HTTP-Anfrageheader werden ausgewertet, bevor die Anwendungsnutzlast verarbeitet wird. Dieses Profil wird für die Identitätsüberprüfung und Zugriffssteuerung verwendet, z. B. zum Delegieren der Autorisierung an Identity-Aware Proxy.
  • Inhaltsbasierte Autorisierung (CONTENT_AUTHZ): Wertet vollständige HTTP-Anfrage- und Antwortnutzlasten aus. Dieses Profil wird für die eingehende Inhaltsprüfung und KI-Sicherheit verwendet, z. B. durch Delegieren an Model Armor für die Prompt- und Antwortsicherheit oder an semantische Governance-Richtlinien für die Durchsetzung von Einschränkungen in natürlicher Sprache.

Benutzerdefinierte Autorisierungs-Engines können entweder REQUEST_AUTHZ- oder CONTENT_AUTHZ-Erweiterungen verwenden, je nachdem, ob sie Header oder vollständige Anwendungsnutzlasten prüfen.

Sie können Autorisierungserweiterungen separat für anfragebasierte und inhaltsbasierte Richtlinien konfigurieren oder beide auf einem Gateway kombinieren, um umfassende Sicherheit zu erreichen. Empfohlene Konfigurationen finden Sie unter Empfohlene Konfiguration für eingehenden und ausgehenden Traffic.

Weitere Informationen zu Autorisierungsrichtlinien, Richtlinienprofilen und ihren Anwendungsfällen finden Sie unter Autorisierungsrichtlinien – Übersicht.

Für umfassende Sicherheit während des gesamten Lebenszyklus von KI-Agenten empfehlen wir das folgende Multi-Gateway-Architekturmuster:

  • Client-zu-Agent-Gateways: Client-zu-Agent-Gateways (eingehend) unterstützen nur eine einzelne CONTENT_AUTHZ-Richtlinie. Das bedeutet, dass Sie Model Armor und semantische Governance-Richtlinien nicht zusammen für eingehenden Traffic verwenden können. Wir empfehlen dringend, eine Model Armor-CONTENT_AUTHZ-Richtlinie zu verwenden, um sich vor Prompt-Injection-Angriffen zu schützen. Wenn Sie stattdessen eine Erweiterung für semantische Governance-Richtlinien verwenden möchten, müssen Sie darauf achten, dass Model Armor nicht auf dem Gateway konfiguriert ist. Andere Arten von Diensterweiterungen werden für Ingress-Gateways nicht unterstützt.

  • Agent-to-Anywhere-Gateways: Agent-to-Anywhere-Gateways (für ausgehenden Traffic) unterstützen bis zu vier Autorisierungsrichtlinien. Gateways für ausgehenden Traffic unterstützen sowohl REQUEST_AUTHZ- als auch CONTENT_AUTHZ-Richtlinienprofile. Sie können innerhalb dieses Limits mehrere Richtlinien jedes Typs konfigurieren.

    Wir empfehlen die folgende Konfiguration:

    • Eine REQUEST_AUTHZ-Richtlinie, die die Autorisierung der Agentenidentität an Identity-Aware Proxy (IAP) delegiert.
    • Eine oder mehrere CONTENT_AUTHZ-Richtlinien, die weitere Entscheidungen an Model Armor oder semantische Governance-Richtlinien delegieren, um die Offenlegung sensibler Daten zu verhindern und Einschränkungen in natürlicher Sprache für ausgehende Toolaufrufe und Antworten durchzusetzen.

    Weitere Informationen zur Auswertung von Richtlinien finden Sie unter Richtlinienauswertung für ausgehenden Traffic.

Diese Multi-Gateway-Topologie sorgt dafür, dass Model Armor eingehende Prompts prüft, während IAP, Model Armor und semantische Governance-Richtlinien ausgehende Antworten prüfen.

Richtlinienbewertung für ausgehenden Traffic

Wenn mehrere Autorisierungsrichtlinien für ein Egress-Gateway konfiguriert sind, werden sie nacheinander gemäß ihrem Richtlinienprofiltyp ausgewertet:

  1. REQUEST_AUTHZ-Richtlinien (headerbasiert): Diese Richtlinientypen werden zuerst ausgewertet. Eine IAP-Erweiterung prüft beispielsweise die mTLS-Identität des aufrufenden Agents und validiert seine IAM-Zulassungsrichtlinien, bevor Inhalte verarbeitet werden. Wenn die Anfrage diese Prüfung nicht besteht, wird sie sofort abgelehnt.
  2. CONTENT_AUTHZ-Richtlinien (inhaltsbasiert): Diese Richtlinientypen werden als Nächstes ausgewertet. Wenn die Anfrage die headerbasierte Prüfung besteht, wird die Nutzlast an die inhaltsbasierte Autorisierungserweiterung (z. B. die Policy Engine für semantische Governance-Richtlinien) gestreamt, um eine eingehende Inhaltsprüfung und Compliance-Bewertung durchzuführen.

Hinweis

Bevor Sie beginnen, sollten Sie prüfen, ob die folgenden Anforderungen erfüllt sind:

  • Das Agent Gateway wird bereitgestellt. Weitere Informationen finden Sie unter Agent Gateway konfigurieren.

  • Sie benötigen die IAM-Berechtigung networkservices.agentGateways.use für die bereitgestellte Agent Gateway-Ressource, um Autorisierungsrichtlinien an das Gateway anhängen zu können.

Autorisierungsrichtlinien mit Erweiterungen konfigurieren

In diesem Abschnitt erfahren Sie, wie Sie Autorisierungsrichtlinien konfigurieren, die Autorisierungs- und Inhaltssicherheitsentscheidungen an Identity-Aware Proxy, Model Armor und andere benutzerdefinierte Dienste delegieren.

Autorisierung an IAP delegieren

Sie können eine Anfrageautorisierungserweiterung konfigurieren, um Zugriffsentscheidungen für Autorisierungsrichtlinien an IAP zu delegieren.

In den folgenden Schritten wird beschrieben, wie Sie eine Autorisierungserweiterung mit einer Autorisierungsrichtlinie für eine Agent Gateway-Instanz konfigurieren.

  1. Hinweis: Deaktivieren Sie die Erzwingung für die verwaltete Organisationsrichtlinieneinschränkung Bindung der Zugriffsrichtlinie an Ressource deaktivieren (constraints/iam.managed.disableAccessPolicyBindings). Standardmäßig ist diese boolesche Einschränkung für neue Organisationen aktiviert und verhindert, dass Sie eine IAM Unified Access Policy an eine Ressource binden. Weitere Informationen finden Sie unter Richtlinien mit booleschen Regeln aktualisieren.

  2. Erstellen Sie die erforderlichen IAM-Richtlinien für ausgehenden Traffic für Ihre KI-Agenten und Tools. Weitere Informationen finden Sie unter IAM-Agent-Richtlinien erstellen.

  3. Informationen zum Aktivieren von IAP beim Erstellen des Agent-Gateways (mit dem Parameter Zugriffsautorisierung) finden Sie unter Agent-Gateway im Agent-to-Anywhere-Modus (ausgehend) konfigurieren.

  4. Konfigurieren Sie eine Autorisierungserweiterung, die auf IAP verweist.

    1. Definieren Sie die Erweiterung in einer YAML-Datei. Verwenden Sie die angegebenen Beispielwerte. Wenn Sie die Erweiterung im reinen Audit-Modus als Probelauf bereitstellen möchten, um die Autorisierungsrichtlinie zu testen, ohne sie zu erzwingen, können Sie das Feld iamEnforcementMode im Block metadata angeben.

      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
      

      Wenn Sie die Erweiterung im reinen Audit-Modus im Probelauf bereitstellen möchten, um die Autorisierungsrichtlinie zu testen, ohne sie zu erzwingen, können Sie das Feld iamEnforcementMode im Block metadata angeben. So können Sie Ihre Richtlinie prüfen und das Risiko von Traffic-Unterbrechungen aufgrund von Konfigurationsfehlern minimieren:

      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
      

      Entfernen Sie das Feld iamEnforcementMode: "DRY_RUN" aus dem Block metadata (oder wählen Sie in der Google Cloud Console Richtlinien erzwingen aus), wenn Sie bereit sind, Richtlinien zu erzwingen. Eine Anleitung zum Prüfen von Verstößen im Probelauf vor dem Aktivieren der Erzwingung finden Sie unter Verstöße gegen Richtlinien im Probelauf über Kontrollen hinweg prüfen.

    2. Importieren Sie die Autorisierungserweiterung. Verwenden Sie den Befehl gcloud service-extensions authz-extensions import mit den folgenden Beispielwerten.

      gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
          --source=iap-request-authz-extension.yaml \
          --location=LOCATION
      
  5. Konfigurieren Sie im selben Projekt eine Autorisierungsrichtlinie, die die Entscheidung an die Erweiterung delegiert.

    1. Definieren Sie eine Autorisierungsrichtlinie, die die Erweiterung my-iap-request-authz-ext mit Ihrem Gateway verknüpft. Verwenden Sie die angegebenen Beispielwerte.

      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
      

      Ersetzen Sie dabei PROJECT_ID durch Ihre Projekt-ID.

    2. Importieren Sie die Autorisierungsrichtlinie in das Projekt. Verwenden Sie den Befehl gcloud network-security authz-policies import mit den folgenden Beispielwerten.

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

Autorisierung an Model Armor delegieren

Sie können eine Autorisierungserweiterung konfigurieren, um Entscheidungen zur Inhaltssicherheit für Autorisierungsrichtlinien an Model Armor zu delegieren. Ihre Model Armor-Vorlagen können sich im selben Projekt wie das Agent Gateway und der Agent oder in einem separaten Projekt befinden, z. B. in einem zentralen Sicherheits- oder Governance-Projekt.

Im folgenden Beispiel wird gezeigt, wie Sie eine solche Autorisierungserweiterung mit einer Autorisierungsrichtlinie für Agent Gateway konfigurieren.

Console

So aktivieren Sie Model Armor für Agent Gateway über die Google Cloud Console:

  1. Erstellen Sie die erforderlichen Model Armor-Vorlagen.

  2. Unter Agent Gateway konfigurieren erfahren Sie, wie Sie Model Armor beim Erstellen des Agent Gateway aktivieren (über das Kästchen Model Armor aktivieren). Model Armor-Vorlagen werden sowohl im Client-zu-Agent- als auch im Agent-zu-Anywhere-Modus unterstützt.

  3. Wenn Sie Model Armor verwenden, müssen Sie dem Agent Gateway-Dienstkonto die Berechtigungen gewähren, die für die Verwendung der Model Armor-Vorlagen erforderlich sind. Das Dienstkonto hat das Format service-PROJECT_NUMBER@gcp-sa-dep., wobei PROJECT_NUMBER die Projektnummer des Projekts ist, in dem Sie das Gateway erstellt haben.

    Sie müssen diesen Schritt auch ausführen, wenn sich sowohl das Gateway als auch die Vorlagen im selben Projekt befinden. Weisen Sie die folgenden Rollen zu:

    • Die Rollen roles/modelarmor.calloutUser und roles/serviceusage.serviceUsageConsumer im Projekt, das das Gateway enthält.
    • Die Rolle roles/modelarmor.user im Projekt, das die Model Armor-Vorlagen enthält.

    Sie müssen die gcloud CLI verwenden, um diesen Schritt auszuführen.

    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
    

    Ersetzen Sie Folgendes:

    • GATEWAY_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie das Gateway erstellt haben.
    • GATEWAY_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie das Gateway erstellt haben.
    • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID des Projekts, das die Model Armor-Vorlage enthält.

    Wenn Sie das Gateway für Agent Runtime verwenden, benötigt der Agent Runtime-Dienst-Agent diese Berechtigungen ebenfalls, wie unter Agent Runtime-Traffic über Agent Gateway weiterleiten beschrieben.

gcloud

  1. Erstellen Sie die erforderlichen Model Armor-Vorlagen.

  2. Wenn Sie Model Armor verwenden, müssen Sie dem Agent Gateway-Dienstkonto die Berechtigungen gewähren, die für die Verwendung der Model Armor-Vorlagen erforderlich sind. Das Dienstkonto hat das Format service-PROJECT_NUMBER@gcp-sa-dep., wobei PROJECT_NUMBER die Projektnummer des Projekts ist, in dem Sie das Gateway erstellt haben.

    Sie müssen diesen Schritt auch ausführen, wenn sich sowohl das Gateway als auch die Vorlagen im selben Projekt befinden. Weisen Sie die folgenden Rollen zu:

    • Die Rollen roles/modelarmor.calloutUser und roles/serviceusage.serviceUsageConsumer im Projekt, das das Gateway enthält.
    • Die Rolle roles/modelarmor.user im Projekt, das die Model Armor-Vorlage enthält.
    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
    

    Ersetzen Sie Folgendes:

    • GATEWAY_PROJECT_ID: Die Projekt-ID des Projekts, in dem Sie das Gateway erstellt haben.
    • GATEWAY_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie das Gateway erstellt haben.
    • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID des Projekts, das die Model Armor-Vorlage enthält.
  3. Konfigurieren Sie die Autorisierungserweiterung so, dass sie auf Model Armor verweist.

    1. Definieren Sie die Erweiterung in einer YAML-Datei. Verwenden Sie die angegebenen Beispielwerte.

      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. Importieren Sie die Autorisierungserweiterung. Verwenden Sie den Befehl gcloud service-extensions authz-extensions import mit den folgenden Beispielwerten.

      gcloud service-extensions authz-extensions import my-ma-content-authz-ext \
         --source=ma-content-authz-extension.yaml \
         --location=LOCATION
      
  4. Konfigurieren Sie eine Autorisierungsrichtlinie mit der Erweiterung.

    1. Definieren Sie eine Autorisierungsrichtlinie, die die Erweiterung my-ma-content-authz-ext mit einem Agent-Gateway verknüpft.

      Agent zu beliebigem Ziel

      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
      

      Wichtige Hinweise:

      • Der Wert von policyProfile ist auf CONTENT_AUTHZ festgelegt. Dies gibt an, dass der benutzerdefinierte Richtlinienanbieter den Anfrage- und Antworttraffic einschließlich des Anfragetexts verarbeitet.

      • Der Parameter httpRules zeigt, wie Sie mit CEL-Attributen Bedingungen erstellen, die dem spezifischen Traffic entsprechen, den Sie zur Auswertung an Model Armor weiterleiten möchten. In diesem Beispiel entsprechen die Regeln dem gesamten Traffic mit den Inhaltstypen application/json oder text/. Wir empfehlen, solche Regeln zu verwenden, um die Model Armor-Bewertung auf relevanten Traffic zu beschränken. So können Sie unterstützten LLM API-, MCP- und A2A-Traffic an Model Armor weiterleiten und internen Traffic wie gRPC-Aufrufe von Agenten ausschließen.

      Client zu Agent

      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
      

      Der Wert von policyProfile ist auf CONTENT_AUTHZ festgelegt. Dies gibt an, dass der benutzerdefinierte Richtlinienanbieter den Anfrage- und Antworttraffic einschließlich des Anfragetexts verarbeitet.

    2. Importieren Sie die Autorisierungsrichtlinie in das Projekt. Verwenden Sie den Befehl gcloud network-security authz-policies import mit den folgenden Beispielwerten.

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

Terraform

Wenn Sie Model Armor-Autorisierungserweiterungen und CONTENT_AUTHZ-Richtlinien deklarativ mit dem google-Anbieter konfigurieren möchten, definieren Sie die erforderlichen IAM-Bindungen für den Dienst-Agent, die Autorisierungserweiterung und die Autorisierungsrichtlinie. Diese Konfiguration gilt unabhängig davon, ob sich Ihre Model Armor-Vorlagen im selben Projekt wie das Agent Gateway und der Agent oder in einem separaten Projekt befinden. Wenn sich Ihre Model Armor-Vorlagen in einem anderen Projekt als dem Projekt befinden, das den Agenten oder das Agent Gateway enthält, und Sie VPC Service Controls verwenden, müssen sich beide Projekte im selben VPC Service Controls-Dienstperimeter befinden.

  1. Weisen Sie dem Service Extensions-Dienst-Agenten die erforderlichen Rollen im Projekt mit dem Agent Gateway und im Projekt mit Ihren Model Armor-Vorlagen zu. Sie müssen diesen Schritt auch dann ausführen, wenn sich sowohl das Gateway als auch die Vorlagen im selben Projekt befinden:

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

    Wenn Sie das Gateway für Agent Runtime verwenden, benötigt der Agent Runtime-Dienst-Agent außerdem Berechtigungen, wie unter Agent Runtime-Traffic über Agent Gateway weiterleiten beschrieben.

  2. Definieren Sie die google_network_services_authz_extension-Ressource, die auf Model Armor verweist:

    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. Hängen Sie die Erweiterung mit einer google_network_security_authz_policy-Ressource an Ihr Agent Gateway an:

    Agent zu beliebigem Ziel

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

    Client zu Agent

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

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Projekt-ID des Projekts, in dem Sie das Agent Gateway erstellt haben.

  • PROJECT_NUMBER: die Projektnummer des Projekts, in dem Sie das Agent Gateway erstellt haben.

  • MODEL_ARMOR_PROJECT_ID: die Projekt-ID des Projekts, das die Model Armor-Vorlage enthält. Dies kann dasselbe Projekt wie PROJECT_ID oder ein separates Projekt sein. Wenn sich die Vorlage in einem anderen Projekt als der Agent oder das Agent Gateway-Projekt befindet und Sie VPC Service Controls verwenden, müssen sich beide Projekte im selben Dienstperimeter befinden.

  • LOCATION: die Region, in der sich Ihr Agent Gateway und Ihre Model Armor-Vorlage befinden.

  • TEMPLATE_ID: die ID der Model Armor-Vorlage.

  • AGENT_GATEWAY_NAME: der Name der Agent-Gateway-Ressource.

Autorisierung an benutzerdefinierte Autorisierungserweiterungen delegieren

Sie können benutzerdefinierte Autorisierungserweiterungen konfigurieren, um Entscheidungen an benutzerdefinierte Dienste zu delegieren. Diese benutzerdefinierten Erweiterungen können nur auf voll qualifizierte Domainnamen (FQDNs) ausgerichtet werden.

Wenn Sie FQDN-Ziele verwenden, nutzt die Erweiterung das HTTP2-Protokoll mit TLS-Verschlüsselung, um mit Endpunkten auf Port 443 zu kommunizieren. Das Serverzertifikat wird von der Erweiterung jedoch nicht validiert. Aus Sicherheitsgründen müssen Sie daher dafür sorgen, dass sich die aufgelösten Endpunkte im VPC-Netzwerk befinden. Achten Sie außerdem darauf, dass DNS-Peering zwischen dem Agent Gateway-Projekt und Ihrem VPC-Netzwerk eingerichtet ist.

  1. Wenn Sie eine Autorisierungserweiterung mit einer Autorisierungsrichtlinie für einen bestimmten FQDN wie mycustomauthz.internal.net konfigurieren möchten, geben Sie ihn in der YAML-Datei der Erweiterung als Wert für service an, wie im folgenden Beispiel gezeigt. In diesem Beispiel wird davon ausgegangen, dass Sie einen Server in Ihrem VPC-Netzwerk bereitgestellt haben, der das ext_proc-Protokoll im Textverarbeitungsmodus FULL_DUPLEX_STREAMED implementiert.

    cat >custom-authz-extension.yaml <<EOF
    name: my-custom-authz-ext
    service: mycustomauthz.internal.net
    failOpen: false
    timeout: 1s
    EOF
    
  2. Erstellen Sie die Autorisierungserweiterung, die auf den benutzerdefinierten Dienst verweist.

    gcloud beta service-extensions authz-extensions import custom-authz-extension \
      --source=custom-authz-extension.yaml \
      --location=LOCATION
    
  3. Nachdem Sie die Erweiterung erstellt haben, konfigurieren Sie eine CUSTOM-Autorisierungsrichtlinie, die Entscheidungen an die Autorisierungserweiterung delegiert.

      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. Erstellen Sie die Autorisierungsrichtlinie.

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

Wenn eine Autorisierungserweiterung mit einer Autorisierungsrichtlinie verknüpft ist, die das Profil CONTENT_AUTHZ verwendet, wie in diesem Beispiel gezeigt, ruft das Gateway die Erweiterung für Anfrage- und Antwortnutzlasten (Header und Text) auf. Dadurch werden eine umfassende Inhaltsprüfung, Prompt-Guardrails und eine Datenbereinigung für den Agent-Traffic ermöglicht. Standardmäßig verwenden CONTENT_AUTHZ-Richtlinien das Envoy-ext_proc-Protokoll im FULL_DUPLEX_STREAMED-Modus, um Textkörperereignisse zu verarbeiten.

IAP-Autorisierung mit Model Armor-Schutzmaßnahmen kombinieren

Für umfassende Sicherheit empfehlen wir, eine BENUTZERDEFINIERTE Autorisierungsrichtlinie mit einem REQUEST_AUTHZ-Richtlinienprofil und eine weitere BENUTZERDEFINIERTE Autorisierungsrichtlinie mit einem CONTENT_AUTHZ-Richtlinienprofil einzurichten.

Im folgenden Beispiel wird IAP als zentrales System zur Autorisierung von Anfragen und Model Armor für KI-Schutzmaßnahmen verwendet. Wie in den vorherigen Beispielen gezeigt, können Sie jede dieser Komponenten durch Diensterweiterungen ersetzen, um Ihre eigenen benutzerdefinierten Lösungen zu verwenden.

  1. Konfigurieren Sie eine REQUEST_AUTHZ-Autorisierungserweiterung, die an IAP delegiert, und eine Autorisierungsrichtlinie, die auf die Erweiterung verweist.

    1. Definieren Sie die Autorisierungserweiterung. Das Feld iapPolicyVersion unter metadata ist ein Pflichtfeld.

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

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

      Ersetzen Sie LOCATION durch die Region der Erweiterung.

    3. Konfigurieren Sie die Autorisierungsrichtlinie REQUEST_AUTHZ, die an die Erweiterung delegiert.

      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
      

      Ersetzen Sie Folgendes:

      • PROJECT_ID: Ihre Projekt-ID.
      • LOCATION: Der Standort der Ressourcen.
      • AGENT_GATEWAY_NAME: Der Name des Agent-Gateways.
    4. Erstellen Sie die Autorisierungsrichtlinie.

      gcloud network-security authz-policies import authz-iap \
      --source=authz-policy-request-authz.yaml \
      --location=LOCATION
      
  2. Konfigurieren Sie eine CONTENT_AUTHZ-Autorisierungserweiterung, die an Model Armor delegiert, und eine Autorisierungsrichtlinie, die auf die Erweiterung verweist.

    1. Definieren Sie die Erweiterung.

      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
      

      Ersetzen Sie Folgendes:

      • LOCATION: Die Region, in der sich Ihre Model Armor-Vorlagen befinden.
      • MODEL_ARMOR_PROJECT_ID: Die Projekt-ID, die die Model Armor-Vorlagen enthält.
      • RESPONSE_TEMPLATE_ID: Die ID der Antwortvorlage.
      • REQUEST_TEMPLATE_ID: Die ID der Anfragevorlage.
    2. Erstellen Sie die Autorisierungserweiterung.

      gcloud service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      
    3. Konfigurieren Sie die Autorisierungsrichtlinie CONTENT_AUTHZ, die an die Erweiterung delegiert.

      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. Erstellen Sie die Autorisierungsrichtlinie.

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

Wenn eine Autorisierungserweiterung mit einem CONTENT_AUTHZ-Profil verknüpft ist, empfängt sie alle ext_proc-Ereignisse, einschließlich Anfrage- und Antwortheader, Text und Trailer. Wenn Ihre ext_proc-basierte Autorisierungserweiterung sowohl die Autorisierung zum Zeitpunkt der Anfrage als auch die inhaltsbasierte Autorisierung verarbeiten kann, empfehlen wir, eine einzelne CUSTOM-Autorisierungsrichtlinie mit dem Richtlinienprofil CONTENT_AUTHZ zu konfigurieren. Diese Richtlinie sollte auf Ihre vielseitige Autorisierungserweiterung verweisen. Dieser Ansatz ermöglicht beide Arten der Autorisierung über eine einzige Erweiterung und ext_proc-Verbindung, was die Latenzprofile verbessern kann.

Autorisierung an semantische Governance-Richtlinien delegieren

Sie können eine Autorisierungserweiterung konfigurieren, um Entscheidungen zur Intent-Gating- und Natural-Language-Einschränkung für Autorisierungsrichtlinien an die Policy Engine für semantische Governance (semanticGovernancePolicyEngine) zu delegieren.

Informationen zum Bereitstellen der Policy Engine und zum Erstellen der erforderlichen CONTENT_AUTHZ-Autorisierungsrichtlinie und der Autorisierungserweiterungsbindung auf Ihrem Gateway finden Sie unter Policy Engine mit Agent Gateway verbinden.

Autorisierung basierend auf MCP-Protokollattributen

Agent Gateway parst die MCP-Protokollnutzlast in einer Anfrage und stellt die extrahierten Attribute für Autorisierungsrichtlinien zur Verfügung.

Sie können den Zugriff basierend auf MCP-Methodenparametern wie den Namen bestimmter Tools einschränken. In diesem Abschnitt finden Sie zwei Beispiele, eines für eine ALLOW-Richtlinie und eines für DENY.

  1. Konfigurieren Sie die Autorisierungsrichtlinie.

    Beispiel für eine ALLOW-Richtlinie

    In diesem Beispiel wird der Zugriff auf eine bestimmte Gruppe von Tools auf dem MCP-Server und die grundlegenden Protokollfunktionen gewährt, der Zugriff auf Prompts und Ressourcen jedoch verweigert.

    Wenn Sie eine ALLOW-Richtlinie schreiben, müssen Sie baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS angeben, damit nicht zugriffsspezifische MCP-RPCs wie Initialisierung, Logging, Abschluss, Benachrichtigungen und Ping weiterhin funktionieren. Andernfalls kann keine MCP-Sitzung eingerichtet werden.

    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
    

    Beispiel für eine DENY-Richtlinie

    In diesem Beispiel wird der Zugriff auf alle Prompts/Methoden für einen MCP-Server hinter einem Agent Gateway verweigert.

    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. Erstellen Sie die Autorisierungsrichtlinie.

    gcloud network-security authz-policies import AUTHZ_POLICY_NAME \
    --source=AUTH_POLICY_YAML_FILE_PATH \
    --location=LOCATION
    

    Ersetzen Sie Folgendes:

    • AUTHZ_POLICY_NAME: Der Name der Autorisierungsrichtlinie.
    • AUTH_POLICY_YAML_FILE_PATH: Der Pfad zur YAML-Datei der Autorisierungsrichtlinie.
    • LOCATION: Der Standort der Ressourcen.

Beschränkungen

Bei der Verwendung von Autorisierungsrichtlinien gelten die folgenden Einschränkungen:

  • Die maximale Anzahl von Autorisierungsrichtlinien pro Gateway hängt vom Gateway-Modus ab:

    • Für Agent-to-Anywhere-Gateways (ausgehend) können Sie maximal vier Autorisierungsrichtlinien pro Gateway konfigurieren, unabhängig vom Richtlinienprofil (REQUEST_AUTHZ oder CONTENT_AUTHZ).
    • Für Client-zu-Agent-Gateways (Ingress) können Sie maximal eine CONTENT_AUTHZ-Richtlinie konfigurieren.

    Weitere Informationen finden Sie unter Empfohlene Konfiguration für eingehenden und ausgehenden Traffic.

  • Wenn Sie benutzerdefinierte Autorisierungserweiterungen mit dem CONTENT_AUTHZ-Profil verwenden, müssen diese das ext_proc-Protokoll und den FULL_DUPLEX_STREAMED-Modus für Body-Ereignisse unterstützen.

  • Wenn Sie mehrere benutzerdefinierte Autorisierungsrichtlinien konfigurieren, die dasselbe Profil verwenden, ist die Ausführungsreihenfolge nicht garantiert.

Weitere Informationen zu den Einschränkungen von Autorisierungserweiterungen finden Sie in den folgenden Abschnitten:

Nächste Schritte

Codelab

Hier erfahren Sie, wie Sie agentische Arbeitslasten mit Agent Gateway auf der Gemini Enterprise Agent Platform verwalten.

Anleitung

Informationen zum Ansehen, Aktualisieren, Aufheben der Verknüpfung und Löschen von Agent Gateway-Ressourcen.

Anleitung

Informationen zum Monitoring des KI-Agenten-Gateways

Fehlerbehebung

Informationen zur Fehlerbehebung bei der Verbindung zum KI-Agenten-Gateway.