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 kontrol akses dan kebijakan tata kelola terpusat pada traffic yang melewati endpoint yang dipublikasikan oleh Agent Gateway. Untuk menangani kontrol akses, keamanan konten, dan keputusan tata kelola yang kompleks, Agent Gateway memungkinkan Anda mengonfigurasi kebijakan otorisasi dengan ekstensi otorisasi yang memungkinkan Anda mendelegasikan otorisasi dan keputusan keamanan konten ke mesin otorisasi yang ditentukan pilihan Anda.

Ekstensi otorisasi mencegat permintaan yang melewati deployment Agent Gateway dan melakukan panggilan gRPC real-time ke layanan otorisasi yang ditentukan. Hal ini memungkinkan layanan untuk memeriksa, mengubah, atau memblokir traffic sebelum dilanjutkan ke tujuannya. Anda dapat mendelegasikan otorisasi ke Google Cloud layanan 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 mereka 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 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 bersama-sama di ingress. Sebaiknya gunakan kebijakan CONTENT_AUTHZModel 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 (keluar) 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 dan respons alat keluar.

    Lihat Evaluasi kebijakan pada traffic keluar 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 traffic keluar

Jika beberapa kebijakan otorisasi dikonfigurasi di gateway keluar, kebijakan tersebut 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 diproses. Jika permintaan gagal dalam pemeriksaan ini, permintaan akan langsung ditolak.
  2. Kebijakan CONTENT_AUTHZ (berbasis konten): Jenis kebijakan ini akan dievaluasi berikutnya. Jika permintaan lolos pemeriksaan berbasis header, payload akan di-streaming 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 Agent Gateway.

  • 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 Agent Gateway.

  1. Sebelum memulai: Nonaktifkan penerapan untuk kebijakan Nonaktifkan akses pengikatan ke resource (constraints/iam.managed.disableAccessPolicyBindings) batasan kebijakan organisasi yang dikelola. Secara default, batasan boolean ini diaktifkan untuk organisasi baru dan akan mencegah Anda mengikat Kebijakan Akses Terpadu IAM ke resource. Untuk mengetahui informasi selengkapnya, lihat Memperbarui kebijakan dengan aturan boolean.

  2. Buat kebijakan keluar 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 Otorisasi akses).

  4. Konfigurasi ekstensi otorisasi untuk mengarah ke IAP.

    1. Tentukan ekstensi dalam file YAML. Gunakan nilai contoh yang diberikan. Jika Anda ingin men-deploy ekstensi dalam mode hanya audit uji coba, 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 hanya audit uji coba, untuk menguji kebijakan otorisasi tanpa menerapkannya, Anda dapat menentukan kolom iamEnforcementMode di dalam blok metadata. Dengan begitu, Anda dapat memverifikasi kebijakan dan meminimalkan risiko gangguan traffic akibat 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 saat Anda siap mulai menerapkan kebijakan.

    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, konfigurasi kebijakan otorisasi yang mendelegasikan keputusan ke ekstensi.

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

      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.

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 Aktifkan Model Armor). Template Model Armor didukung dalam mode Client-to-Agent dan Agent-to-Anywhere.

  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.iam.gserviceaccount.com, 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.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

    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.iam.gserviceaccount.com, 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.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

    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. Konfigurasi ekstensi otorisasi untuk 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 contoh nilai berikut.

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

  4. Mengonfigurasi kebijakan otorisasi dengan ekstensi.

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

      Agen ke Mana Saja 

      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 disetel 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 evaluasi. Dalam contoh ini, aturan cocok dengan semua traffic dengan jenis konten application/json atau text/. Sebaiknya gunakan aturan tersebut untuk membatasi evaluasi Model Armor pada traffic yang relevan. Dengan begitu, Anda dapat merutekan traffic LLM API, MCP, dan A2A yang didukung ke Model Armor sambil 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 disetel 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

Mendelegasikan otorisasi ke ekstensi otorisasi kustom

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

Saat Anda menggunakan target FQDN, ekstensi 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 Agent Gateway 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 membuat ekstensi, konfigurasi CUSTOM kebijakan otorisasi 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 mendalam, panduan 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 pengaman Model Armor

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

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

  1. Konfigurasi 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. Konfigurasi kebijakan otorisasi REQUEST_AUTHZ yang didelegasikan 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. Konfigurasi 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. Konfigurasi kebijakan otorisasi CONTENT_AUTHZ yang didelegasikan 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 ekstensi otorisasi dikaitkan dengan profil CONTENT_AUTHZ, ekstensi tersebut akan menerima semua peristiwa ext_proc, termasuk header permintaan dan respons, isi, dan trailer. Jika ekstensi otorisasi berbasis ext_proc Anda dapat menangani otorisasi waktu permintaan dan otorisasi berbasis konten, sebaiknya konfigurasi 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 niat dan batasan bahasa alami untuk kebijakan otorisasi ke mesin kebijakan tata kelola semantik (semanticGovernancePolicyEngine).

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

Otorisasi berdasarkan atribut protokol MCP

Agent Gateway mengurai payload protokol MCP dalam permintaan dan membuat atribut yang diekstrak tersedia 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. Konfigurasi kebijakan otorisasi.

    Contoh kebijakan ALLOW

    Contoh ini memungkinkan 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 khusus seperti inisialisasi, logging, penyelesaian, notifikasi, dan ping terus berfungsi. Jika tidak dilakukan, sesi MCP tidak 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 tidak mengizinkan semua akses metode/ prompt 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 (keluar), Anda dapat mengonfigurasi maksimal empat kebijakan otorisasi per gateway, terlepas dari profil kebijakan (REQUEST_AUTHZ atau CONTENT_AUTHZ).
    • Untuk gateway Client-to-Agent (ingress), Anda dapat mengonfigurasi maksimal 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 beban kerja agentic dengan Agent Gateway di Gemini Enterprise Agent Platform.

Panduan

Pelajari cara memantau Agent Gateway.

Pemecahan masalah

Pelajari cara memecahkan masalah konektivitas Agent Gateway.