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 otorisasi memungkinkan Anda menerapkan kontrol akses dan kebijakan tata kelola terpusat pada traffic yang melewati endpoint yang dipublikasikan oleh Agent Gateway. Kebijakan ini memungkinkan Anda mengelola traffic dengan mengontrol akses berdasarkan identitas mTLS, atribut permintaan dan respons, serta menyesuaikan berdasarkan atribut khusus protokol yang digunakan (misalnya, server MCP).
Kebijakan otorisasi menggunakan profil kebijakan untuk menentukan jenis
otorisasi yang akan dilakukan. Anda dapat menggunakan kebijakan otorisasi berbasis permintaan
(REQUEST_AUTHZ) yang mengandalkan informasi di header permintaan HTTP untuk mengizinkan atau
menolak traffic. Atau, Anda dapat menggunakan kebijakan otorisasi berbasis konten
(CONTENT_AUTHZ) saat perlu melakukan pemeriksaan lebih mendalam terhadap payload
aplikasi untuk mengizinkan atau menolak traffic.
Untuk mempelajari lebih lanjut kebijakan otorisasi, profil kebijakan, dan kasus penggunaannya, lihat Ringkasan kebijakan otorisasi.
Ekstensi otorisasi
Terkadang, keputusan otorisasi yang kompleks tidak dapat dinyatakan dengan mudah menggunakan kebijakan otorisasi. Agent Gateway memungkinkan Anda mengonfigurasi kebijakan otorisasi dengan ekstensi otorisasi untuk mendelegasikan keputusan otorisasi ke mesin otorisasi kustom.
Ekstensi otorisasi memungkinkan Anda mencegat dan mengevaluasi permintaan yang melewati deployment Agent Gateway. Hal ini membuat panggilan gRPC real-time ke layanan eksternal yang Anda kelola, sehingga Anda dapat memeriksa, mengubah, atau bahkan memblokir traffic sebelum melanjutkan ke tujuannya.
Ekstensi memeriksa data berdasarkan kebijakan otorisasi yang dikonfigurasi. Anda dapat mengonfigurasi ekstensi otorisasi secara terpisah untuk kebijakan otorisasi berbasis permintaan dan berbasis konten, atau Anda dapat menggunakan keduanya untuk keamanan yang komprehensif.
Sebelum memulai
Sebelum memulai, pastikan Anda memenuhi persyaratan berikut:
Agent Gateway di-deploy. Lihat Mengonfigurasi Agent Gateway.
Anda harus memiliki izin IAM
agentGateway.usepada 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 otorisasi dan keputusan 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.
Contoh berikut menunjukkan cara mengonfigurasi ekstensi otorisasi dengan kebijakan otorisasi untuk instance Agent Gateway.
Konsol
Untuk menggunakan konsol Google Cloud guna mengaktifkan IAP untuk Agent Gateway, lakukan langkah-langkah berikut:
- Buat kebijakan keluar IAM yang diperlukan untuk agen dan alat Anda. Untuk mengetahui informasi selengkapnya, lihat Membuat kebijakan agen IAM.
Lihat Mengonfigurasi Agent Gateway dalam mode Agent-to-Anywhere (Egress) untuk mengaktifkan IAP saat membuat Agent Gateway (dengan menggunakan parameter Otorisasi akses).
IAP mewajibkan agen Anda didaftarkan dengan resource Agent Registry yang terikat ke gateway.
gcloud
Konfigurasi ekstensi otorisasi untuk mengarah ke IAP.
Tentukan ekstensi dalam file YAML. Gunakan nilai sampel yang diberikan.
cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true EOFJika ingin men-deploy ekstensi dalam mode hanya audit uji coba, untuk menguji kebijakan otorisasi tanpa menerapkannya, Anda dapat menentukan kolom
DRY_RUN. Dengan begitu, Anda dapat memverifikasi kebijakan dan meminimalkan risiko terganggunya traffic karena error konfigurasi:cat >iap-request-authz-extension.yaml <<EOF name: my-iap-request-authz-ext service: iap.googleapis.com failOpen: true metadata: ' iamEnforcementMode: DRY_RUN ' EOFImpor ekstensi otorisasi. Gunakan perintah
gcloud beta service-extensions authz-extensions importdengan nilai contoh berikut.gcloud beta service-extensions authz-extensions import my-iap-request-authz-ext \ --source=iap-request-authz-extension.yaml \ --location=LOCATION
Dalam project yang sama, konfigurasi kebijakan otorisasi yang mendelegasikan keputusan ke ekstensi.
Tentukan kebijakan otorisasi yang mengaitkan ekstensi
my-iap-authz-request-extdengan gateway Anda. Gunakan nilai contoh 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" EOFGanti
PROJECT_IDdengan project ID Anda.Impor kebijakan otorisasi ke project. Gunakan perintah
gcloud beta network-security authz-policies importdengan nilai contoh berikut.gcloud beta 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:
Buat template Model Armor yang diperlukan.
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.
Jika template Model Armor Anda berada dalam project yang berbeda dengan gateway, Anda harus memberikan peran yang diperlukan secara manual ke akun layanan Agent Gateway. Akun layanan memiliki format:
service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, dengan PROJECT_NUMBER adalah nomor project tempat Anda membuat gateway.Berikan peran berikut:
- Peran
roles/modelarmor.calloutUserdanroles/serviceusage.serviceUsageConsumerdalam project yang berisi gateway. - Peran
roles/modelarmor.userdalam 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 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 Reasoning Engine juga memerlukan izin ini seperti yang didokumentasikan dalam Merutekan traffic Agent Runtime melalui Agent Gateway.
- Peran
gcloud
Buat template Model Armor yang diperlukan.
Jika template Model Armor Anda berada dalam project yang berbeda dengan gateway, Anda harus memberikan peran yang diperlukan secara manual ke akun layanan Agent Gateway. Akun layanan memiliki format:
service-PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com, dengan PROJECT_NUMBER adalah nomor project tempat Anda membuat gateway.Berikan peran berikut:
- Peran
roles/modelarmor.calloutUserdanroles/serviceusage.serviceUsageConsumerdalam project yang berisi gateway. - Peran
roles/modelarmor.userdalam 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 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.
- Peran
Konfigurasi ekstensi otorisasi untuk mengarah ke Model Armor.
Tentukan ekstensi dalam file YAML. Gunakan nilai sampel 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: true timeout: 1s EOFImpor ekstensi otorisasi. Gunakan perintah
gcloud beta service-extensions authz-extensions importdengan nilai contoh berikut.gcloud beta service-extensions authz-extensions import my-ma-content-authz-ext \ --source=ma-content-authz-extension.yaml \ --location=LOCATION
Konfigurasi kebijakan otorisasi dengan ekstensi.
Tentukan kebijakan otorisasi yang mengaitkan ekstensi
my-ma-content-authz-extdengan Agent Gateway.cat >ma-content-authz-policy.yaml <<EOF name: my-ma-content-authz-policy target: resources: - "projects/PROJECT_ID/locations/LOCATION/gateways/AGENT_GATEWAY_NAME" policyProfile: CONTENT_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - "projects/PROJECT_ID/locations/LOCATION/authzExtensions/my-ma-content-authz-ext" EOFUntuk kebijakan otorisasi konten, nilai
policyProfileditetapkan sebagaiCONTENT_AUTHZ. Nilai ini menunjukkan bahwa penyedia kebijakan kustom memproses traffic permintaan dan respons, termasuk pemrosesan isi.Impor kebijakan otorisasi ke project. Gunakan perintah
gcloud beta network-security authz-policies importdengan nilai contoh berikut.gcloud beta 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 diselesaikan berada dalam jaringan VPC. Pastikan juga Anda telah menyiapkan peering DNS antara project Agent Gateway dan jaringan VPC Anda.
Untuk mengonfigurasi ekstensi otorisasi dengan kebijakan otorisasi untuk FQDN tertentu, seperti
mycustomauthz.internal.net, tetapkan sebagai nilai untukservicedalam file YAML ekstensi seperti yang ditunjukkan contoh berikut. Contoh ini mengasumsikan bahwa Anda telah men-deploy server di jaringan VPC yang menerapkan protokolext_authz.cat >custom-authz-extension.yaml <<EOF name: my-custom-authz-ext service: mycustomauthz.internal.net failOpen: true wireFormat: EXT_AUTHZ_GRPC EOFBuat ekstensi otorisasi untuk mengarah ke layanan kustom.
gcloud beta service-extensions authz-extensions import custom-authz-extension
--source=custom-authz-extension.yaml
--location=LOCATIONSetelah membuat ekstensi, konfigurasikan
CUSTOMkebijakan 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: REQUEST_AUTHZ action: CUSTOM customProvider: authzExtension: resources: - projects/PROJECT_ID/locations/LOCATION/authzExtensions/custom-authz-extension EOFBuat kebijakan otorisasi.
gcloud beta 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 REQUEST_AUTHZ seperti yang ditunjukkan dalam contoh ini, gateway hanya memanggil ekstensi saat header permintaan tiba. Isi permintaan, header respons, dan isi respons tidak dapat dilihat oleh ekstensi otorisasi.
Menggabungkan otorisasi IAP dengan pedoman 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.
Konfigurasi ekstensi otorisasi
REQUEST_AUTHZyang didelegasikan ke IAP dan kebijakan otorisasi yang mengarah ke ekstensi.Tentukan ekstensi otorisasi.
$ cat >iap-extension.yaml <<EOF name: iap-extension service: iap.googleapis.com failOpen: true EOFBuat ekstensi otorisasi.
gcloud beta service-extensions authz-extensions import iap-extension \ --source=iap-extension.yaml \ --location=LOCATION
Ganti
LOCATIONdengan region ekstensi.Konfigurasi kebijakan otorisasi
REQUEST_AUTHZyang 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" EOFGanti kode berikut:
PROJECT_ID: Project ID Anda.LOCATION: Lokasi resource.AGENT_GATEWAY_NAME: Nama Agent Gateway.
Buat kebijakan otorisasi.
gcloud beta network-security authz-policies import authz-iap \ --source=authz-policy-request-authz.yaml \ --location=LOCATION
Konfigurasi ekstensi otorisasi
CONTENT_AUTHZyang mendelegasikan ke Model Armor dan kebijakan otorisasi yang mengarah ke ekstensi.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: true timeout: 1s EOFGanti 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.
Buat ekstensi otorisasi.
gcloud beta service-extensions authz-extensions import ma-extension \ --source=ma-extension-file.yaml \ --location=LOCATION
Konfigurasi kebijakan otorisasi
CONTENT_AUTHZyang 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" EOFBuat kebijakan otorisasi.
gcloud beta 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 respons, isi, dan trailer. Jika ekstensi otorisasi berbasis ext_proc Anda dapat 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 latensi
dibandingkan dengan menggunakan ekstensi terpisah untuk profil REQUEST_AUTHZ dan CONTENT_AUTHZ.
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.
Konfigurasi kebijakan otorisasi.
Contoh kebijakan
ALLOWContoh 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 menentukanbaseProtocolMethodsOption: MATCH_BASE_PROTOCOL_METHODSagar RPC MCP non-akses tertentu 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 EOFContoh kebijakan
DENYContoh ini melarang semua akses metode/ prompt ke server MCP di belakang 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 EOFBuat kebijakan otorisasi.
gcloud beta 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:
- Anda dapat mengonfigurasi maksimal empat kebijakan otorisasi kustom per Agent Gateway, terlepas dari profil kebijakan.
- Jika Anda menggunakan ekstensi otorisasi kustom dengan profil
CONTENT_AUTHZ, ekstensi tersebut harus mendukung protokolext_procdan modeFULL_DUPLEX_STREAMEDuntuk 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:
Untuk batasan yang berlaku untuk semua ekstensi, lihat Batasan ekstensi.
Untuk mengetahui batasan yang berlaku pada info promo, lihat Batasan info promo.