Memecahkan masalah Unified Access Policies IAM

Dokumen ini membantu Anda mendiagnosis dan menyelesaikan masalah umum saat mengonfigurasi dan menerapkan Kebijakan Akses Terpadu (UAP) IAM untuk egress Agent Gateway.

Kegagalan akses dan penerapan kebijakan

Bagian ini menjelaskan masalah terkait penerapan.

Kebijakan tidak diterapkan

Gejala: Agen dapat mengakses alat tujuan, server MCP, atau endpoint meskipun aturan penolakan IAM atau aturan izin yang membatasi dikonfigurasi untuk memblokir akses.

Penyebab: Ekstensi otorisasi Agent Gateway berjalan dalam mode uji coba, atau cakupan binding kebijakan tidak cocok dengan resource target. Dalam mode uji coba, keputusan akses dievaluasi dan dicatat dalam log untuk audit, tetapi permintaan tidak pernah diblokir.

Solusi:

  1. Mengalihkan mode uji coba ke mode penerapan: Pertama, periksa file konfigurasi ekstensi otorisasi Anda (iap-request-authz-extension.yaml). Jika iamEnforcementMode ditetapkan ke "DRY_RUN", perbarui ke "ENFORCE" (atau hapus setelan DRY_RUN) dan impor ulang ekstensi menggunakan gcloud CLI:

    gcloud service-extensions authz-extensions import EXTENSION_NAME \
    --source=EXTENSION_FILE.yaml \
    --location=LOCATION

    Ganti kode berikut:

    • EXTENSION_NAME: nama ekstensi otorisasi Anda
    • EXTENSION_FILE: nama file konfigurasi ekstensi YAML Anda
    • LOCATION: Cloud de Confiance region tempat gateway Anda di-deploy

  2. Memverifikasi delegasi kebijakan otorisasi gateway: Pastikan kebijakan otorisasi gateway (policyProfile: REQUEST_AUTHZ) terikat ke instance Agent Gateway yang benar (target.resources).

  3. Memeriksa cakupan binding kebijakan: Pastikan UAP IAM terikat ke cakupan resource target tempat traffic tiba.

  4. Memeriksa prioritas aturan: Dalam kebijakan kombinasi, aturan penolakan secara eksplisit mengganti aturan izin pada cakupan yang sama. Namun, periksa apakah UAP dengan aturan izin yang lebih luas yang terikat di tingkat project atau registry memberikan akses tanpa batasan kondisi.

Kebijakan terkait Proses Penegakan Kebijakan memblokir akses agen

Gejala: Permintaan egress agen gagal dengan error HTTP 403 Forbidden atau PERMISSION_DENIED error saat penerapan kebijakan Agent Gateway diaktifkan.

Penyebab:

  • Identitas agen tidak ditentukan dalam UAP.

  • Identitas agen tidak diberi izin iap.resources.egressViaIAP pada resource tujuan.

  • Nama host tujuan yang tepat tidak terdaftar di Agent Registry

  • Atribut permintaan tidak memenuhi kondisi Common Expression Language (CEL) dalam UAP.

Solusi:

  1. Beralih ke mode uji coba untuk proses debug yang tidak mengganggu: Saat mendiagnosis kegagalan, alihkan ekstensi otorisasi ke mode uji coba (iamEnforcementMode: "DRY_RUN") untuk sementara agar traffic agen aktif tidak diblokir saat Anda memeriksa log audit.

  2. Mengkueri Cloud Audit Logs: Kueri Cloud Audit Logs untuk memeriksa pemeriksaan otorisasi dan evaluasi atribut CEL yang tepat:

    gcloud

    Jalankan perintah gcloud logging read berikut:

    gcloud logging read \
    'protoPayload.serviceName="iap.googleapis.com" AND protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP" AND protoPayload.status.code!=0' \
    --project=PROJECT_ID \
    --limit=20

    Ganti PROJECT_ID dengan project ID Anda.

    Konsol

    1. Di Cloud de Confiance konsol, buka halaman Logs Explorer.
    2. Pilih project Anda.
    3. Di editor kueri, masukkan kueri berikut: 
          protoPayload.serviceName="iap.googleapis.com"
    protoPayload.authorizationInfo.permission="iap.resources.egressViaIAP"
    protoPayload.status.code!=0
    4. Klik Run query.
    5. Luaskan entri log dan periksa protoPayload.authorizationInfo untuk melihat URI resource target dan izin mana yang gagal dievaluasi.

  3. Memverifikasi kecocokan nama host yang tepat: Agent Gateway mencocokkan nama host tujuan secara tepat. Layanan pihak ketiga atau Google API dapat diselesaikan melalui beberapa variasi nama host, bergantung pada versi SDK versi, konfigurasi klien regional, atau penggunaan mTLS—misalnya, us-central1-aiplatform.googleapis.com versus us-central1-aiplatform.mtls.googleapis.com versus aiplatform.googleapis.com.

    • Jika Anda mengandalkan target terdaftar, pastikan setiap variasi nama host yang tepat terdaftar di Agent Registry.
    • Jika agen mengakses endpoint yang tidak terdaftar, pastikan bahwa kebijakan endpoint yang tidak terdaftar memberikan iap.resources.egressViaIAP untuk host dan jalur tersebut.

  4. Memverifikasi cakupan binding kebijakan di seluruh cakupan: Periksa apakah binding kebijakan ada di salah satu dari tiga cakupan yang didukung:

    • Di seluruh registry: Memberikan akses ke semua agen, server MCP, dan endpoint di registry.
    • Per resource: Memberikan akses ke server MCP, endpoint, atau agen terdaftar tertentu.
    • Endpoint yang tidak terdaftar: Memberikan akses ke tujuan di luar Agent Registry.
    • Catatan: Saat menjelaskan binding kebijakan untuk resource target, jika output yang ditampilkan berisi kolom "etag" tetapi tidak ada binding, tidak ada kebijakan IAM untuk target tersebut.

Pesan error UI, gcloud, dan REST API umum

Bagian ini menjelaskan pesan error dan cara menyelesaikannya.

Kebijakan tidak ditemukan

Pesan error:

  • UI Konsol: "Kebijakan yang diminta tidak ada. Pastikan kebijakan ada untuk resource yang dipilih."
  • API / gcloud: POLICY_NOT_FOUND / HTTP 404 Not Found

Penyebab: ID UAP yang ditentukan dalam permintaan update atau binding kebijakan Anda tidak ada di project atau lokasi, atau telah dihapus.

Solusi: Cantumkan semua UAP yang tersedia di project Anda menggunakan gcloud iam access-policies list --project=<var>PROJECT_ID</var> --location=global untuk mengonfirmasi ID dan lokasi kebijakan yang tepat sebelum mengikat atau memperbaruinya.

Batas binding target terlampaui

Pesan error:

  • UI Konsol: "Target yang dipilih telah mencapai batasnya untuk binding kebijakan akses. Hapus binding yang ada sebelum menambahkan yang baru."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_PER_TARGET

Penyebab: Anda mencoba melampirkan lebih banyak binding kebijakan ke resource target (seperti server atau registry MCP) daripada batas maksimum yang diizinkan per target.

Solusi: Alih-alih membuat UAP dan binding terpisah untuk setiap aturan, gabungkan beberapa aturan izin atau penolakan ke dalam satu UAP. Hapus binding yang tidak digunakan menggunakan gcloud iam policy-bindings delete.

Batas binding kebijakan terlampaui

Pesan error:

  • UI Konsol: "Kebijakan yang dipilih telah mencapai batasnya untuk binding. Hapus binding yang ada sebelum menambahkan yang baru."
  • API / gcloud: TOO_MANY_ACCESS_POLICY_BINDINGS_TO_POLICY

Penyebab: Satu UAP dilampirkan ke terlalu banyak resource target yang berbeda di seluruh project Anda.

Solusi: Ikat kebijakan pada cakupan yang lebih luas—seperti cakupan di seluruh registry (AgentRegistry) atau cakupan project—dan gunakan kondisi atribut CEL (seperti destination.agent_registry.mcp_server.name) untuk mengatur akses ke alat individual dalam aturan kebijakan.

Batas kondisi terlampaui

Pesan error:

  • UI Konsol: "Kebijakan ini telah mencapai jumlah maksimum kondisi atribut kondisi. Hapus beberapa kondisi untuk menyimpan perubahan."
  • API / gcloud: TOO_MANY_CONDITIONS / Condition limit exceeded for rule in policy.

Penyebab: Satu aturan izin atau penolakan berisi lebih banyak kondisi atribut Kontrol Akses Terperinci (FGAC) atau sub-ekspresi kompleks daripada yang didukung dalam satu aturan.

Solusi: Gabungkan pemeriksaan atribut menggunakan operator logis CEL (&&, ||) atau setel pencarian penyertaan (in), atau pisahkan ekspresi Anda ke beberapa aturan dalam UAP yang sama.

Detail aturan yang tidak berlaku

Pesan error:

  • UI Konsol: "Detail aturan tidak berlaku. Aturan ini diubah oleh pengguna lain setelah halaman ini dimuat. Muat ulang halaman untuk mengambil detail saat ini sebelum mengedit atau menghapus."
  • API / gcloud: HTTP 412 Precondition Failed / ABORTED due to etag mismatch.

Penyebab: Administrator lain atau proses otomatis mengubah UAP setelah Anda mengambilnya, sehingga etag berbeda dari status server aktif.

Solusi: Muat ulang halaman Konsol untuk mengambil detail kebijakan aktif dan etag sebelum menyimpan hasil edit Anda. Saat menggunakan REST API, lakukan GET permintaan terlebih dahulu untuk mengambil nilai "etag" aktif, dan sertakan dalam PATCH payload permintaan Anda.

Tidak dapat menghapus aturan terakhir dalam kebijakan

Pesan error:

  • UI Konsol: "Tidak dapat menghapus aturan ini. 'Kebijakan default' harus berisi minimal satu aturan. Untuk menghapus aturan ini, hapus kebijakan." atau "Ini adalah aturan terakhir di <policy name>. Menghapusnya juga akan menghapus kebijakan dan menghapus semua binding terkait secara permanen, yang dapat memengaruhi akses agen ke resource."

Penyebab: UAP IAM tidak dapat disimpan tanpa aturan.

Solusi: Jika Anda ingin menghapus satu-satunya aturan dalam kebijakan, hapus seluruh kebijakan. Ingatlah bahwa Anda harus menghapus semua binding kebijakan yang mereferensikan kebijakan sebelum dapat menghapus kebijakan itu sendiri.

Ekspresi CEL kustom dipertahankan di tab Lanjutan

Pesan error:

  • UI Konsol: "Ekspresi CEL kustom tidak dapat dikonversi menjadi pilihan UI standar. Ekspresi Anda dipertahankan di tab Lanjutan."

Penyebab: Anda memasukkan kondisi atau fungsi CEL yang kompleks di Editor kondisi (tab Lanjutan) yang tidak dapat dipetakan ke pemilih drop-down yang disederhanakan dari pembuat kondisi standar.

Solusi: Pesan ini adalah notifikasi informasi. Kondisi CEL kustom Anda valid dan dipertahankan. Lanjutkan untuk membuat perubahan apa pun langsung di dalam tab Editor kondisi.

Langkah berikutnya