Mendelegasikan otorisasi dengan Service Extensions

Gunakan halaman ini untuk mempelajari cara mendelegasikan otorisasi untuk Agent Gateway ke Identity-Aware Proxy, Model Armor, dan mesin otorisasi kustom lainnya menggunakan Service Extensions.

Kebijakan dan ekstensi otorisasi

Kebijakan otorisasi memungkinkan Anda menerapkan kebijakan kontrol akses dan tata kelola terpusat pada traffic yang melewati endpoint yang dipublikasikan oleh Agent Gateway. Untuk menangani keputusan kontrol akses, keamanan konten, dan tata kelola yang kompleks, Agent Gateway memungkinkan Anda mengonfigurasi kebijakan otorisasi dengan ekstensi otorisasi yang memungkinkan Anda mendelegasikan keputusan otorisasi dan keamanan konten ke mesin otorisasi yang Anda pilih.

Ekstensi otorisasi menangkap permintaan yang melewati deployment Agent Gateway dan melakukan panggilan gRPC real-time ke layanan otorisasi yang ditentukan. Hal ini memungkinkan layanan memeriksa, mengubah, atau memblokir traffic sebelum melanjutkan ke tujuannya. Anda dapat mendelegasikan otorisasi ke layanan Google Cloud seperti Identity-Aware Proxy, Model Armor, dan kebijakan tata kelola semantik, atau ke mesin otorisasi kustom pilihan Anda.

Kebijakan otorisasi menggunakan profil kebijakan untuk menentukan jenis data traffic yang dikirim ke ekstensi otorisasi:

  • Otorisasi berbasis permintaan (REQUEST_AUTHZ): Mengevaluasi header permintaan HTTP sebelum payload aplikasi diproses. Profil ini digunakan untuk verifikasi identitas dan kontrol akses, seperti mendelegasikan otorisasi ke Identity-Aware Proxy.
  • Otorisasi berbasis konten (CONTENT_AUTHZ): Mengevaluasi payload permintaan dan respons HTTP lengkap. Profil ini digunakan untuk pemeriksaan konten mendalam dan keamanan AI, seperti mendelegasikan ke Model Armor untuk keamanan perintah dan respons atau ke kebijakan tata kelola semantik untuk penegakan batasan bahasa alami.

Mesin otorisasi kustom dapat menggunakan ekstensi REQUEST_AUTHZ atau CONTENT_AUTHZ, bergantung pada apakah mesin tersebut memeriksa header atau payload aplikasi lengkap.

Anda dapat mengonfigurasi ekstensi otorisasi secara terpisah untuk kebijakan berbasis permintaan dan berbasis konten, atau menggabungkan keduanya di gateway untuk keamanan yang komprehensif. Untuk konfigurasi yang direkomendasikan, lihat Konfigurasi ingress dan egress yang direkomendasikan.

Untuk mempelajari lebih lanjut kebijakan otorisasi, profil kebijakan, dan kasus penggunaannya, lihat Ringkasan kebijakan otorisasi.

Untuk keamanan yang komprehensif di seluruh siklus proses agen, sebaiknya gunakan pola arsitektur multi-gateway berikut:

  • Gateway klien ke agen: Gateway klien ke agen (ingress) hanya mendukung satu kebijakan CONTENT_AUTHZ. Artinya, Anda tidak dapat menggunakan Model Armor dan kebijakan tata kelola semantik secara bersamaan pada ingress. Kami sangat menyarankan penggunaan kebijakan CONTENT_AUTHZ Model Armor untuk melindungi dari serangan injeksi perintah. Namun, jika Anda ingin menggunakan ekstensi kebijakan tata kelola semantik, Anda harus memastikan bahwa Model Armor tidak dikonfigurasi di gateway. Jenis ekstensi layanan lainnya tidak didukung untuk gateway ingress.

  • Gateway Agent-to-Anywhere: Gateway Agent-to-Anywhere (egress) mendukung hingga empat kebijakan otorisasi. Gateway egress mendukung profil kebijakan REQUEST_AUTHZ dan CONTENT_AUTHZ, dan Anda dapat mengonfigurasi beberapa kebijakan dari setiap jenis dalam batas ini.

    Sebaiknya gunakan konfigurasi berikut:

    • Kebijakan REQUEST_AUTHZ yang mendelegasikan ke Identity-Aware Proxy (IAP) untuk mengizinkan identitas agen.
    • Satu atau beberapa kebijakan CONTENT_AUTHZ yang mendelegasikan keputusan lebih lanjut ke Model Armor atau kebijakan tata kelola semantik untuk melindungi dari eksposur data sensitif dan menerapkan batasan bahasa alami pada panggilan alat dan respons keluar.

    Lihat Evaluasi kebijakan pada egress untuk mengetahui informasi selengkapnya tentang cara kebijakan dievaluasi.

Topologi multi-gateway ini memastikan bahwa Model Armor menyaring perintah yang masuk, sementara IAP, Model Armor, dan kebijakan tata kelola semantik menyaring respons yang keluar.

Evaluasi kebijakan pada egress

Jika beberapa kebijakan otorisasi dikonfigurasi di gateway traffic keluar, kebijakan tersebut akan dievaluasi secara berurutan sesuai dengan jenis profil kebijakannya:

  1. Kebijakan REQUEST_AUTHZ (berbasis header): Jenis kebijakan ini dievaluasi terlebih dahulu. Misalnya, ekstensi IAP memeriksa identitas mTLS agen yang memanggil dan memvalidasi kebijakan izin IAM-nya sebelum konten apa pun diproses. Jika permintaan gagal dalam pemeriksaan ini, permintaan akan langsung ditolak.
  2. Kebijakan CONTENT_AUTHZ (berbasis konten): Jenis kebijakan ini dievaluasi berikutnya. Jika permintaan lulus pemeriksaan berbasis header, payload akan distreaming ke ekstensi otorisasi berbasis konten (seperti mesin kebijakan tata kelola semantik) untuk pemeriksaan konten mendalam dan evaluasi kepatuhan.

Sebelum memulai

Sebelum memulai, pastikan Anda memenuhi persyaratan berikut:

  • Agent Gateway di-deploy. Lihat Mengonfigurasi Gateway Agen.

  • Anda harus memiliki izin IAM networkservices.agentGateways.use pada resource Agent Gateway yang di-deploy agar dapat melampirkan kebijakan otorisasi ke gateway.

Mengonfigurasi kebijakan otorisasi dengan ekstensi

Bagian ini menunjukkan cara mengonfigurasi kebijakan otorisasi yang mendelegasikan keputusan otorisasi dan keamanan konten ke Identity-Aware Proxy, Model Armor, dan layanan kustom lainnya.

Mendelegasikan otorisasi ke IAP

Anda dapat mengonfigurasi ekstensi otorisasi permintaan untuk mendelegasikan keputusan akses untuk kebijakan otorisasi ke IAP.

Langkah-langkah berikut menunjukkan cara mengonfigurasi ekstensi otorisasi dengan kebijakan otorisasi untuk instance Gateway Agen.

  1. Sebelum memulai: Nonaktifkan penerapan untuk batasan kebijakan organisasi terkelola Disable binding access policy to resource (constraints/iam.managed.disableAccessPolicyBindings). Secara default, batasan boolean ini diaktifkan untuk organisasi baru dan akan mencegah Anda mengikat IAM Unified Access Policy ke resource. Untuk mengetahui informasi selengkapnya, lihat Memperbarui kebijakan dengan aturan boolean.

  2. Buat kebijakan egress IAM yang diperlukan untuk agen dan alat Anda. Untuk mengetahui informasi selengkapnya, lihat Membuat kebijakan agen IAM.

  3. Lihat Mengonfigurasi Gateway Agen dalam mode Agent-to-Anywhere (Egress) untuk mengaktifkan IAP saat membuat Gateway Agen (dengan menggunakan parameter Access authorization).

  4. Konfigurasikan ekstensi otorisasi agar mengarah ke IAP.

    1. Tentukan ekstensi dalam file YAML. Gunakan nilai contoh yang diberikan. Jika Anda ingin men-deploy ekstensi dalam mode uji coba khusus audit, untuk menguji kebijakan otorisasi tanpa menerapkannya, Anda dapat menentukan kolom iamEnforcementMode di dalam blok 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
      

      Jika Anda ingin men-deploy ekstensi dalam mode uji coba khusus audit, untuk menguji kebijakan otorisasi tanpa menerapkannya, Anda dapat menentukan kolom iamEnforcementMode di dalam blok metadata. Hal ini memungkinkan Anda memverifikasi kebijakan dan meminimalkan risiko gangguan traffic karena kesalahan konfigurasi:

      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
      

      Hapus kolom iamEnforcementMode: "DRY_RUN" dari blok metadata (atau pilih Enforce policies di konsol Google Cloud ) saat Anda siap untuk mulai menerapkan kebijakan. Untuk mengetahui petunjuk tentang cara mengaudit pelanggaran uji coba sebelum mengaktifkan penerapan, lihat Mengaudit pelanggaran kebijakan uji coba di seluruh kontrol.

    2. Impor ekstensi otorisasi. Gunakan perintah gcloud service-extensions authz-extensions import dengan nilai contoh berikut.

      gcloud service-extensions authz-extensions import my-iap-request-authz-ext \
          --source=iap-request-authz-extension.yaml \
          --location=LOCATION
      
  5. Dalam project yang sama, konfigurasikan kebijakan otorisasi yang mendelegasikan keputusan ke ekstensi.

    1. Tentukan kebijakan otorisasi yang mengaitkan ekstensi my-iap-request-authz-ext dengan gateway Anda. Gunakan nilai contoh yang disediakan.

      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
      

      Ganti PROJECT_ID dengan project ID Anda.

    2. Impor kebijakan otorisasi ke project. Gunakan perintah gcloud network-security authz-policies import dengan nilai contoh berikut.

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

Mendelegasikan otorisasi ke Model Armor

Anda dapat mengonfigurasi ekstensi otorisasi untuk mendelegasikan keputusan keamanan konten untuk kebijakan otorisasi ke Model Armor. Template Model Armor Anda dapat berada di project yang sama dengan Agent Gateway dan agen atau di project terpisah, seperti project keamanan atau tata kelola pusat.

Contoh berikut menunjukkan cara mengonfigurasi ekstensi otorisasi tersebut dengan kebijakan otorisasi untuk Agent Gateway.

Konsol

Untuk menggunakan konsol Google Cloud guna mengaktifkan Model Armor untuk Agent Gateway, lakukan langkah-langkah berikut:

  1. Buat template Model Armor yang diperlukan.

  2. Lihat Mengonfigurasi Agent Gateway untuk mengaktifkan Model Armor saat membuat Agent Gateway (dengan menggunakan kotak centang Enable Model Armor). Template Model Armor didukung dalam mode Klien-ke-Agen dan Agen-ke-Mana Saja.

  3. Saat menggunakan Model Armor, Anda harus memberikan izin yang diperlukan kepada akun layanan Agent Gateway agar dapat menggunakan template Model Armor. Akun layanan memiliki format: service-PROJECT_NUMBER@gcp-sa-dep., dengan PROJECT_NUMBER adalah nomor project tempat Anda membuat gateway.

    Anda harus menyelesaikan langkah ini meskipun gateway dan template berada dalam project yang sama. Berikan peran berikut:

    • Peran roles/modelarmor.calloutUser dan roles/serviceusage.serviceUsageConsumer dalam project yang berisi gateway.
    • Peran roles/modelarmor.user dalam project yang berisi template Model Armor.

    Anda harus menggunakan gcloud CLI untuk menyelesaikan langkah ini.

    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
    

    Ganti kode berikut:

    • GATEWAY_PROJECT_ID: Project ID dari project tempat Anda membuat gateway.
    • GATEWAY_PROJECT_NUMBER: Nomor project dari project tempat Anda membuat gateway.
    • MODEL_ARMOR_PROJECT_ID: Project ID dari project yang berisi template Model Armor.

    Jika Anda menggunakan gateway untuk Agent Runtime, agen layanan Agent Runtime juga memerlukan izin ini seperti yang didokumentasikan dalam Merutekan traffic Agent Runtime melalui Agent Gateway.

gcloud

  1. Buat template Model Armor yang diperlukan.

  2. Saat menggunakan Model Armor, Anda harus memberikan izin yang diperlukan kepada akun layanan Agent Gateway agar dapat menggunakan template Model Armor. Akun layanan memiliki format: service-PROJECT_NUMBER@gcp-sa-dep., dengan PROJECT_NUMBER adalah nomor project tempat Anda membuat gateway.

    Anda harus menyelesaikan langkah ini meskipun gateway dan template berada dalam project yang sama. Berikan peran berikut:

    • Peran roles/modelarmor.calloutUser dan roles/serviceusage.serviceUsageConsumer dalam project yang berisi gateway.
    • Peran roles/modelarmor.user dalam project yang berisi template 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
    

    Ganti kode berikut:

    • GATEWAY_PROJECT_ID: Project ID dari project tempat Anda membuat gateway.
    • GATEWAY_PROJECT_NUMBER: Nomor project dari project tempat Anda membuat gateway.
    • MODEL_ARMOR_PROJECT_ID: Project ID dari project yang berisi template Model Armor.
  3. Konfigurasikan ekstensi otorisasi agar mengarah ke Model Armor.

    1. Tentukan ekstensi dalam file YAML. Gunakan nilai contoh yang diberikan.

      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. Impor ekstensi otorisasi. Gunakan perintah gcloud service-extensions authz-extensions import dengan nilai contoh berikut.

      gcloud service-extensions authz-extensions import my-ma-content-authz-ext \
         --source=ma-content-authz-extension.yaml \
         --location=LOCATION
      
  4. Konfigurasikan kebijakan otorisasi dengan ekstensi.

    1. Tentukan kebijakan otorisasi yang mengaitkan ekstensi my-ma-content-authz-ext dengan Gateway Agen.

      Agent-to-Anywhere

      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
      

      Perhatikan hal berikut:

      • Nilai policyProfile ditetapkan ke CONTENT_AUTHZ. Hal ini menunjukkan bahwa penyedia kebijakan kustom memproses traffic permintaan dan respons, termasuk isi permintaan.

      • Parameter httpRules menunjukkan cara menggunakan atribut CEL untuk membuat kondisi yang cocok dengan traffic tertentu yang ingin Anda teruskan ke Model Armor untuk dievaluasi. Dalam contoh ini, aturan mencocokkan semua traffic dengan jenis konten application/json atau text/. Sebaiknya gunakan aturan tersebut untuk membatasi evaluasi Model Armor ke traffic yang relevan. Dengan begitu, Anda dapat merutekan traffic API LLM, MCP, dan A2A yang didukung ke Model Armor, sekaligus mengecualikan traffic internal seperti panggilan gRPC agen.

      Klien ke Agen

      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
      

      Nilai policyProfile ditetapkan ke CONTENT_AUTHZ. Hal ini menunjukkan bahwa penyedia kebijakan kustom memproses traffic permintaan dan respons, termasuk isi permintaan.

    2. Impor kebijakan otorisasi ke project. Gunakan perintah gcloud network-security authz-policies import dengan nilai contoh berikut.

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

Terraform

Untuk mengonfigurasi ekstensi otorisasi Model Armor dan kebijakan CONTENT_AUTHZ secara deklaratif menggunakan penyedia google, tentukan binding IAM agen layanan, ekstensi otorisasi, dan kebijakan otorisasi yang diperlukan. Konfigurasi ini berlaku baik jika template Model Armor Anda berada dalam project yang sama dengan Agent Gateway dan agen, atau dalam project terpisah. Jika template Model Armor Anda berada di project yang berbeda dengan project yang berisi agen atau Gateway Agen dan Anda menggunakan Kontrol Layanan VPC, kedua project harus berada dalam perimeter layanan Kontrol Layanan VPC yang sama.

  1. Berikan peran yang diperlukan kepada agen layanan Service Extensions di project yang berisi Agent Gateway dan di project yang berisi template Model Armor Anda. Anda harus menyelesaikan langkah ini meskipun gateway dan template berada dalam project yang sama:

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

    Jika Anda menggunakan gateway untuk Agent Runtime, agen layanan Agent Runtime juga memerlukan izin seperti yang didokumentasikan dalam Merutekan traffic Agent Runtime melalui Agent Gateway.

  2. Tentukan resource google_network_services_authz_extension yang mengarah ke 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. Lampirkan ekstensi ke Agent Gateway Anda dengan resource google_network_security_authz_policy:

    Agent-to-Anywhere

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

    Klien ke Agen

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

Ganti kode berikut:

  • PROJECT_ID: project ID dari project tempat Anda membuat Gateway Agen.

  • PROJECT_NUMBER: nomor project dari project tempat Anda membuat Gateway Agen.

  • MODEL_ARMOR_PROJECT_ID: project ID untuk project yang berisi template Model Armor. Project ini dapat berupa project yang sama dengan PROJECT_ID atau project terpisah. Jika template berada di project yang berbeda dengan project agen atau Gateway Agen dan Anda menggunakan Kontrol Layanan VPC, kedua project harus berada dalam perimeter layanan yang sama.

  • LOCATION: region tempat Gateway Agen dan template Model Armor Anda berada.

  • TEMPLATE_ID: ID template Model Armor.

  • AGENT_GATEWAY_NAME: nama resource Agent Gateway.

Mendelegasikan otorisasi ke ekstensi otorisasi kustom

Anda dapat mengonfigurasi ekstensi otorisasi kustom untuk mendelegasikan keputusan ke layanan kustom. Ekstensi kustom ini hanya dapat menarget nama domain yang sepenuhnya memenuhi syarat (FQDN).

Saat Anda menggunakan target FQDN, ekstensi akan menggunakan protokol HTTP2 dengan enkripsi TLS untuk berkomunikasi dengan endpoint di port 443. Namun, ekstensi tidak memvalidasi sertifikat server. Oleh karena itu, untuk keamanan yang lebih baik, Anda harus memastikan bahwa endpoint yang di-resolve berada dalam jaringan VPC. Pastikan juga Anda telah menyiapkan peering DNS antara project Gateway Agen dan jaringan VPC Anda.

  1. Untuk mengonfigurasi ekstensi otorisasi dengan kebijakan otorisasi untuk FQDN tertentu, seperti mycustomauthz.internal.net, tentukan sebagai nilai untuk service dalam file YAML ekstensi seperti yang ditunjukkan contoh berikut. Contoh ini mengasumsikan bahwa Anda telah men-deploy server di jaringan VPC yang menerapkan protokol ext_proc dalam mode pemrosesan isi FULL_DUPLEX_STREAMED.

    cat >custom-authz-extension.yaml <<EOF
    name: my-custom-authz-ext
    service: mycustomauthz.internal.net
    failOpen: false
    timeout: 1s
    EOF
    
  2. Buat ekstensi otorisasi untuk mengarah ke layanan kustom.

    gcloud beta service-extensions authz-extensions import custom-authz-extension \
      --source=custom-authz-extension.yaml \
      --location=LOCATION
    
  3. Setelah Anda membuat ekstensi, konfigurasikan kebijakan otorisasi CUSTOM yang mendelegasikan keputusan ke ekstensi otorisasi.

      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. Buat kebijakan otorisasi.

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

Perhatikan bahwa saat ekstensi otorisasi dikaitkan dengan kebijakan otorisasi menggunakan profil CONTENT_AUTHZ seperti yang ditunjukkan dalam contoh ini, gateway akan memanggil ekstensi untuk payload permintaan dan respons (header dan isi), sehingga memungkinkan pemeriksaan konten yang mendalam, guardrail perintah, dan sanitasi data untuk traffic agen Anda. Secara default, kebijakan CONTENT_AUTHZ menggunakan protokol ext_proc Envoy dalam mode FULL_DUPLEX_STREAMED untuk memproses peristiwa isi.

Menggabungkan otorisasi IAP dengan guardrail Model Armor

Untuk keamanan yang komprehensif, sebaiknya siapkan kebijakan otorisasi CUSTOM dengan profil kebijakan REQUEST_AUTHZ dan kebijakan otorisasi CUSTOM lainnya dengan profil kebijakan CONTENT_AUTHZ.

Contoh berikut menggunakan IAP sebagai sistem otorisasi permintaan terpusat dan Model Armor untuk guardrail AI. Seperti yang ditunjukkan dalam contoh sebelumnya, Anda dapat menukar masing-masing dengan ekstensi layanan untuk menggunakan solusi kustom Anda sendiri.

  1. Konfigurasikan ekstensi otorisasi REQUEST_AUTHZ yang mendelegasikan ke IAP dan kebijakan otorisasi yang mengarah ke ekstensi.

    1. Tentukan ekstensi otorisasi. Kolom iapPolicyVersion di bagian metadata wajib diisi.

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

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

      Ganti LOCATION dengan region ekstensi.

    3. Konfigurasikan kebijakan otorisasi REQUEST_AUTHZ yang mendelegasikan ke ekstensi.

      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
      

      Ganti kode berikut:

      • PROJECT_ID: Project ID Anda.
      • LOCATION: Lokasi resource.
      • AGENT_GATEWAY_NAME: Nama Agent Gateway.
    4. Buat kebijakan otorisasi.

      gcloud network-security authz-policies import authz-iap \
      --source=authz-policy-request-authz.yaml \
      --location=LOCATION
      
  2. Konfigurasikan ekstensi otorisasi CONTENT_AUTHZ yang mendelegasikan ke Model Armor dan kebijakan otorisasi yang mengarah ke ekstensi.

    1. Tentukan ekstensi.

      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
      

      Ganti kode berikut:

      • LOCATION: Region tempat template Model Armor Anda berada.
      • MODEL_ARMOR_PROJECT_ID: Project ID yang berisi template Model Armor.
      • RESPONSE_TEMPLATE_ID: ID template respons.
      • REQUEST_TEMPLATE_ID: ID template permintaan.
    2. Buat ekstensi otorisasi.

      gcloud service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      
    3. Konfigurasikan kebijakan otorisasi CONTENT_AUTHZ yang mendelegasikan ke ekstensi.

      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. Buat kebijakan otorisasi.

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

Saat dikaitkan dengan profil CONTENT_AUTHZ, ekstensi otorisasi akan menerima semua peristiwa ext_proc, termasuk header permintaan dan header respons, isi, dan trailer. Jika ekstensi otorisasi berbasis ext_proc Anda mampu menangani otorisasi waktu permintaan dan otorisasi berbasis konten, sebaiknya konfigurasikan satu kebijakan otorisasi CUSTOM dengan profil kebijakan CONTENT_AUTHZ. Kebijakan ini harus mengarah ke ekstensi otorisasi serbaguna Anda. Pendekatan ini memungkinkan kedua jenis otorisasi melalui satu ekstensi dan koneksi ext_proc, yang dapat meningkatkan profil latensi.

Mendelegasikan otorisasi ke kebijakan tata kelola semantik

Anda dapat mengonfigurasi ekstensi otorisasi untuk mendelegasikan keputusan pembatasan intent dan batasan bahasa alami untuk kebijakan otorisasi ke Policy Engine tata kelola semantik (semanticGovernancePolicyEngine).

Untuk mempelajari cara menyediakan policy engine dan membuat kebijakan otorisasi CONTENT_AUTHZ dan binding ekstensi otorisasi yang diperlukan di gateway Anda, lihat Menghubungkan policy engine ke Agent Gateway.

Otorisasi berdasarkan atribut protokol MCP

Agent Gateway mengurai payload protokol MCP dalam permintaan dan menyediakan atribut yang diekstrak untuk kebijakan otorisasi.

Anda dapat membatasi akses berdasarkan parameter metode MCP seperti nama alat tertentu. Bagian ini menunjukkan dua contoh, satu untuk kebijakan ALLOW dan satu untuk DENY.

  1. Konfigurasikan kebijakan otorisasi.

    Contoh kebijakan ALLOW

    Contoh ini mengizinkan akses ke serangkaian alat tertentu di server MCP dan fitur protokol dasar, tetapi tidak mengizinkan akses ke perintah dan resource.

    Saat menulis kebijakan ALLOW, pastikan Anda menentukan baseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODS agar RPC MCP non-akses tertentu seperti inisialisasi, logging, penyelesaian, notifikasi, dan ping terus berfungsi. Jika tidak dilakukan, sesi MCP tidak akan dapat dibuat.

    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
    

    Contoh kebijakan DENY

    Contoh ini melarang semua akses prompt/metode ke server MCP di balik 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. Buat kebijakan otorisasi.

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

    Ganti kode berikut:

    • AUTHZ_POLICY_NAME: Nama kebijakan otorisasi.
    • AUTH_POLICY_YAML_FILE_PATH: Jalur ke file YAML kebijakan otorisasi.
    • LOCATION: Lokasi resource.

Batasan

Batasan berikut berlaku saat Anda menggunakan kebijakan otorisasi:

  • Jumlah maksimum kebijakan otorisasi per gateway bergantung pada mode gateway:

    • Untuk gateway Agent-to-Anywhere (egress), Anda dapat mengonfigurasi maksimum empat kebijakan otorisasi per gateway, terlepas dari profil kebijakan (REQUEST_AUTHZ atau CONTENT_AUTHZ).
    • Untuk gateway Klien-ke-Agen (ingress), Anda dapat mengonfigurasi maksimum satu kebijakan CONTENT_AUTHZ.

    Untuk mengetahui informasi selengkapnya, lihat Konfigurasi ingress dan egress yang direkomendasikan.

  • Jika Anda menggunakan ekstensi otorisasi kustom dengan profil CONTENT_AUTHZ, ekstensi tersebut harus mendukung protokol ext_proc dan mode FULL_DUPLEX_STREAMED untuk peristiwa isi.

  • Jika Anda mengonfigurasi beberapa kebijakan otorisasi kustom yang menggunakan profil yang sama, urutan eksekusinya tidak dijamin.

Selain itu, lihat bagian berikut untuk mengetahui informasi selengkapnya tentang batasan ekstensi otorisasi:

Langkah berikutnya

Codelab

Pelajari cara mengelola workload agentic dengan Agent Gateway di Gemini Enterprise Agent Platform.

Panduan

Pelajari cara melihat, memperbarui, membatalkan pengaitan, dan menghapus resource Agent Gateway.

Panduan

Pelajari cara memantau Agent Gateway.

Pemecahan masalah

Pelajari cara memecahkan masalah konektivitas Agent Gateway.