Membatasi izin agen dengan kredensial tercakup

Saat agen orchestrator Anda memanggil agen Agent2Agent (A2A) jarak jauh, kredensial pencakupan membantu memastikan bahwa agen jarak jauh hanya menerima izin yang diperlukan untuk permintaan tersebut. Setelah menemukan agen di Agent Registry, Anda dapat menyertakan kredensial pengguna atau membuat token tercakup menggunakan pengelola autentikasi Agent Identity dengan cakupan OAuth terbatas atau Batas Akses Kredensial untuk Cloud Storage.

Sebelum memulai

Sebelum Anda membatasi izin agen dengan kredensial tercakup untuk panggilan A2A, selesaikan langkah-langkah berikut:

  1. Menyiapkan Agent Registry.

  2. Untuk penyiapan project tunggal, dapatkan project ID dari project tata kelola tempat Agent Registry diaktifkan. Jika Anda mengonfigurasi batas pengelolaan untuk beberapa project, gunakan ID project pengelolaan Anda untuk penemuan dan pendaftaran di seluruh batas, atau tentukan ID project anggota untuk operasi project tunggal.

  3. Jika Anda ingin membatasi token Cloud Storage, aktifkan Security Token Service API (sts.googleapis.com) di project Anda.

  4. Instal library Python google-auth dan requests:

    pip install --upgrade google-auth requests

  5. Konfigurasi Kredensial Default Aplikasi (ADC) untuk pengembangan lokal. Jika tidak, lampirkan akun layanan atau konfigurasi kredensial Workload Identity Federation:

    gcloud auth application-default login

Peran yang diperlukan

Anda dapat menggunakan akun pengguna untuk pengembangan lokal, atau menggunakan akun layanan atau akun utama agen untuk agen orchestrator Anda guna menemukan agen terdaftar dan memanggil agen A2A target. Akun pengguna, akun layanan, atau akun utama agen harus memiliki peran yang sesuai untuk menyelesaikan tugas ini.

Untuk memastikan bahwa akun pengguna, akun layanan, atau entitas agen Anda memiliki izin yang diperlukan untuk menemukan agen A2A di Agent Registry dan memanggil agen A2A target, minta administrator untuk memberikan peran IAM berikut kepada akun pengguna, akun layanan, atau entitas agen Anda:

  • Untuk menemukan agen di Agent Registry: Agent Registry API Viewer (roles/agentregistry.viewer) pada project tata kelola tempat Agent Registry diaktifkan
  • Untuk memanggil agen A2A target saat runtime: Peran runtime atau gateway untuk layanan yang menghosting agen target, yang diperlukan untuk memanggil agen tersebut. Misalnya, jika agen target berjalan di Cloud Run, akun atau akun utama harus memiliki peran Cloud Run Invoker (roles/run.invoker).

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Administrator Anda mungkin juga dapat memberikan izin yang diperlukan kepada akun pengguna, akun layanan, atau akun utama agen Anda melalui peran khusus atau peran bawaan lainnya.

Cara kredensial diteruskan antar-agen

Saat klien A2A atau agen orchestrator mengirim pesan ke agen jarak jauh, layanan downstream akan memeriksa izin berdasarkan cara permintaan diautentikasi:

  • Atas nama pengguna: pengguna login ke agen orchestrator Anda, yang meneruskan token OAuth 2.0 yang diizinkan pengguna, atau token yang dikelola oleh pengelola autentikasi, ke agen A2A jarak jauh. Google Cloud API memverifikasi token dan memeriksa izin Identity and Access Management (IAM) pengguna sehingga agen jarak jauh tidak dapat mengakses resource yang tidak diizinkan untuk diakses oleh pengguna.
  • Menggunakan identitas agen itu sendiri: saat agen orchestrator berjalan tanpa pengguna yang login, agen tersebut melakukan autentikasi dengan identitas agen atau akun layanannya sendiri. Layanan downstream memeriksa peran yang diberikan ke akun utama agen tersebut (principal://), set akun utama yang cocok (principalSet://), atau akun layanannya.
  • Dari workload eksternal atau lintas cloud: agen yang berjalan di luar Google Cloud menukarkan token dari penyedia identitas eksternal melalui Workload Identity Federation untuk mendapatkan token akses Google Cloud gabungan sebelum memanggil endpoint agen A2A target.

Untuk membatasi izin yang diberikan token kepada agen jarak jauh, Anda dapat membatasi cakupan token OAuth dengan binding untuk agen A2A pihak ketiga atau SaaS.

Anda juga dapat membatasi token Cloud Storage menggunakan Batas Akses Kredensial untuk membatasi token akses Google Cloud ke bucket atau objek Cloud Storage tertentu. Batas Akses Kredensial hanya mendukung izin Cloud Storage (storage.googleapis.com). Untuk API lain Google Cloud dan panggilan agen A2A, cakup akses melalui binding pengelola autentikasi, identitas agen dengan hak istimewa terendah dengan kebijakan izin dan penolakan IAM, atau Agent Gateway.

Jika opsi tersebut tidak sesuai dengan kasus penggunaan Anda dan agen orchestrator Anda melakukan autentikasi dengan akun layanan, Anda juga dapat menggunakan peniruan akun layanan untuk meminta token dengan masa aktif singkat untuk akun layanan khusus yang hanya memiliki peran yang diperlukan untuk tugas tertentu.

Membatasi cakupan token OAuth dengan binding

Saat memanggil agen A2A SaaS atau pihak ketiga yang menggunakan OAuth 2.0 2-legged atau 3-legged, buat penyedia autentikasi di pengelola autentikasi dan lampirkan resource Binding di Registry Agen yang hanya mencantumkan scopes OAuth yang diperlukan agen jarak jauh. Saat Agent Development Kit (ADK) mengambil agen jarak jauh menggunakan get_remote_a2a_agent(), ADK akan meminta token yang dibatasi untuk cakupan pada binding tersebut. Untuk mengetahui langkah-langkah penyiapan, lihat Melakukan autentikasi ke alat dan resource dan Mengelola binding.

Membatasi token Cloud Storage

Jika agen orchestrator Anda meneruskan token akses OAuth 2.0 ke agen atau alat yang membaca atau menulis data Cloud Storage, Anda dapat mengurangi izin token agar hanya mengizinkan akses ke bucket atau awalan objek tertentu. Gunakan Layanan Token Keamanan untuk menerapkan Batas Akses Kredensial sebelum mengirim permintaan:

import google.auth
from google.auth import downscoped
from google.auth.transport.requests import Request

source_creds, _ = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

access_boundary_rule = downscoped.AccessBoundaryRule(
    available_resource=(
        "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
    ),
    available_permissions=["inRole:roles/storage.objectViewer"],
)
cab = downscoped.CredentialAccessBoundary(rules=[access_boundary_rule])

downscoped_creds = downscoped.Credentials(
    source_credentials=source_creds,
    credential_access_boundary=cab,
)
downscoped_creds.refresh(Request())

Ganti BUCKET_NAME dengan nama bucket Cloud Storage yang dapat dibaca oleh agen jarak jauh.

Kontrol keamanan tambahan

Anda dapat menggabungkan cakupan kredensial dengan kebijakan jaringan dan pemeriksaan perintah:

  • Kebijakan akses jaringan: merutekan panggilan A2A melalui Agent Gateway untuk menerapkan Unified Access Policies (UAP) Identity-Aware Proxy (IAP) pada resource Agent yang terdaftar.
  • Pemeriksaan perintah dan respons: konfigurasikan integrasi Model Armor dengan Agent Gateway dan binding ekstensi layanan untuk memeriksa perintah dan respons A2A yang didukung terkait injeksi perintah dan eksposur data sensitif.

Langkah berikutnya