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 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.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 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:

  1. Buat kebijakan keluar IAM yang diperlukan untuk agen dan alat Anda. Untuk mengetahui informasi selengkapnya, lihat Membuat kebijakan agen IAM.
  2. 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

  1. Konfigurasi ekstensi otorisasi untuk mengarah ke IAP.

    1. 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
      EOF
      

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

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

    1. Tentukan kebijakan otorisasi yang mengaitkan ekstensi my-iap-authz-request-ext dengan 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"
      EOF
      

      Ganti PROJECT_ID dengan project ID Anda.

    2. Impor kebijakan otorisasi ke project. Gunakan perintah gcloud beta network-security authz-policies import dengan 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:

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

gcloud

  1. Buat template Model Armor yang diperlukan.

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

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

    1. Tentukan kebijakan otorisasi yang mengaitkan ekstensi my-ma-content-authz-ext dengan 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"
      EOF
      

      Untuk kebijakan otorisasi konten, nilai policyProfile ditetapkan sebagai CONTENT_AUTHZ. Nilai ini menunjukkan bahwa penyedia kebijakan kustom memproses traffic permintaan dan respons, termasuk pemrosesan isi.

    2. Impor kebijakan otorisasi ke project. Gunakan perintah gcloud beta network-security authz-policies import dengan 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.

  1. Untuk mengonfigurasi ekstensi otorisasi dengan kebijakan otorisasi untuk FQDN tertentu, seperti mycustomauthz.internal.net, tetapkan 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_authz.

    cat >custom-authz-extension.yaml <<EOF
    name: my-custom-authz-ext
    service: mycustomauthz.internal.net
    failOpen: true
    wireFormat: EXT_AUTHZ_GRPC
    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, 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
      EOF
    
  4. Buat 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.

  1. Konfigurasi ekstensi otorisasi REQUEST_AUTHZ yang didelegasikan ke IAP dan kebijakan otorisasi yang mengarah ke ekstensi.

    1. Tentukan ekstensi otorisasi.

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

      gcloud beta 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 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 beta 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: true
      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 beta service-extensions authz-extensions import ma-extension \
      --source=ma-extension-file.yaml \
      --location=LOCATION
      
    3. Konfigurasi 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 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.

  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 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
    EOF
    

    Contoh kebijakan DENY

    Contoh 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
    EOF
    
  2. Buat 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 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

Panduan

Pelajari cara memantau Agent Gateway.