Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mengautentikasi agen AI Anda

Saat men-deploy agen ke Cloud Run, Anda dapat memberinya identitas yang memungkinkannya melakukan autentikasi dengan aman saat berkomunikasi dengan API dan agen lainnya.

Melakukan autentikasi ke Google Cloud API, agen lain, dan alat

Jika beban kerja Cloud Run Anda dikonfigurasi dengan jenis identitas agent-identity, beban kerja tersebut akan menerima identitas yang dikelola sistem dalam format berikut:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Untuk project tanpa organisasi, formatnya menggunakan nomor project:

principal://agents.global.project-PROJECT_NUMBER.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME

Anda dapat menggunakan identitas ini untuk mengautentikasi agen Anda secara aman saat berkomunikasi dengan Google Cloud API, agen lain, atau alat.

Melakukan autentikasi ke Google Cloud API

Agen dapat menggunakan identitas agen yang ditetapkan untuk melakukan autentikasi ke APIGoogle Cloud seperti Vertex AI, Cloud Storage, dan produk Google Cloud lainnya menggunakan token akses yang diambil dari server metadata Cloud Run.

Berikan peran IAM yang sesuai ke akun utama agen Anda, misalnya:
- Memberikan akses ke Vertex AI:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="AGENT_PRINCIPAL" \
    --role="roles/aiplatform.user"
```
- Memberikan akses ke Google Cloud API lainnya:
  
  Berikan peran yang diperlukan pada resource target Anda ke AGENT_PRINCIPAL, misalnya, roles/storage.objectViewer pada bucket Cloud Storage. Untuk mengetahui detailnya, lihat Mengautentikasi dengan Kredensial Default Aplikasi.
Ganti kode berikut:
- PROJECT_ID: Google Cloud Project ID Anda.
- AGENT_PRINCIPAL: identitas agen Anda, misalnya, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/AGENT_NAME.
Dalam kode aplikasi agen, gunakan library klien Google Cloud standar. Library klien secara otomatis menggunakan Kredensial Default Aplikasi (ADC) untuk mengambil token akses berumur pendek dari server metadata.

Atau, Anda dapat mengambil token akses secara manual dari server metadata di dalam container Anda:
```
curl -s -H "Metadata-Flavor: Google" \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token"
```

Melakukan autentikasi ke agen lain di Cloud Run

Saat agen perlu memanggil agen lain yang dihosting di Cloud Run, seperti agen A2A, lakukan autentikasi menggunakan token identitas Token Web JSON (JWT) yang divalidasi oleh pemeriksaan IAM roles/run.invoker bawaan Cloud Run:

Berikan peran roles/run.invoker pada identitas agen pemanggil di layanan Cloud Run target:
```
gcloud run services add-iam-policy-binding TARGET_SERVICE_NAME \
    --member="CALLER_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION
```
Ganti kode berikut:
- TARGET_SERVICE_NAME: nama layanan agen Cloud Run tujuan.
- CALLER_AGENT_PRINCIPAL: identitas agen panggilan.
- REGION: Google Cloud region layanan target.

Opsi validasi token

Cloud Run mendukung dua metode validasi token identitas:

Token tidak terikat: token identitas standar yang terikat dengan audiens yang dibuat oleh server metadata. Ini adalah mekanisme default untuk autentikasi layanan-ke-layanan dan agen-ke-agen.
Token terikat: menyediakan pengikatan kriptografi antara token dan sertifikat beban kerja menggunakan mTLS. Untuk menggunakan token terikat, klien yang memanggil menyediakan rantai sertifikat leaf-nya dalam permintaan.

Anda dapat menggunakan token terikat mTLS untuk memanggil resource Cloud Run yang dikonfigurasi dengan ingress=internal. Dengan begitu, Anda dapat membatasi akses internet publik ke agen atau server MCP tanpa memerlukan jaringan VPC.

Mengambil token ID yang tidak terikat

Dari dalam penampung agen panggilan, ambil token identitas dengan URL layanan target sebagai audiens:
```
TOKEN=$(curl -s -H "Metadata-Flavor: Google" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_URL")
```
Ganti TARGET_SERVICE_URL dengan URL layanan Cloud Run tujuan, misalnya, https://target-agent-1234567890.us-central1.run.app.

Kirim permintaan ke layanan target dengan token di header Authorization:

curl -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_URL/endpoint

Mengambil token ID terikat (mTLS)

Dari dalam container agen panggilan, baca rantai sertifikat leaf Anda dan minta token terikat dari server metadata menggunakan permintaan POST:

CERT_PATH="/var/run/secrets/workload-spiffe-credentials/certificates.pem"
JSON_PAYLOAD=$(jq -n --arg certs "$(cat $CERT_PATH)" '{"certificate_chain": $certs}')

TOKEN=$(curl -s -X POST \
    -H "Metadata-Flavor: Google" \
    -H "Content-Type: application/json" \
    -d "$JSON_PAYLOAD" \
  "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=TARGET_SERVICE_MTLS_URL")

Panggil endpoint mTLS layanan target, dengan menampilkan sertifikat workload selama TLS handshake:

KEY_PATH="/var/run/secrets/workload-spiffe-credentials/private_key.pem"

curl --cert $CERT_PATH \
    --key $KEY_PATH \
    -H "Authorization: Bearer $TOKEN" \
  TARGET_SERVICE_MTLS_URL/endpoint

Contoh Python

Jika Anda menulis kode agen berbasis Python, library klien Google Cloud standar akan otomatis meminta token terikat secara default saat sertifikat ada. Jika Anda perlu membuat permintaan HTTP manual:

import os
import requests
import google.auth
from google.auth.transport.requests import Request
from google.oauth2 import id_token

# Target agent's mTLS URL
target_mtls_url = "TARGET_SERVICE_MTLS_URL"

# 1. Fetch the ID token.
# google-auth automatically requests a bound ID token via POST because
# the platform configures the workload certificate environment variables.
auth_req = Request()
token = id_token.fetch_id_token(auth_req, target_mtls_url)

# 2. Make the HTTP call over mTLS, presenting the workload certificates.
cert_path = "/var/run/secrets/workload-spiffe-credentials/certificates.pem"
key_path = "/var/run/secrets/workload-spiffe-credentials/private_key.pem"

response = requests.get(
    target_mtls_url,
    headers={"Authorization": f"Bearer {token}"},
    cert=(cert_path, key_path)
)
print(response.text)

Ganti TARGET_SERVICE_MTLS_URL dengan URL mTLS dari layanan Cloud Run tujuan, misalnya, https://target-agent-12345.us-central1.mtls.run.app.

Melakukan autentikasi ke server MCP di Cloud Run

Untuk terhubung ke server atau alat MCP yang dihosting di Cloud Run, gunakan ID --functional-type=mcp-server untuk mengaktifkan pendaftaran otomatis server MCP di Agent Registry.

Jika server MCP Anda hanya diakses oleh agen lain yang berjalan di Cloud Run, gunakan pemeriksaan pemanggil IAM bawaan. Izinkan agen Anda berkomunikasi secara native menggunakan kebijakan pemanggil eksekusi standar:

gcloud run services add-iam-policy-binding MCP_SERVICE_NAME \
    --member="CALLING_AGENT_PRINCIPAL" \
    --role="roles/run.invoker" \
    --region=REGION

Ganti kode berikut:

MCP_SERVICE_NAME: nama layanan Cloud Run tujuan yang menghosting server MCP.
CALLING_AGENT_PRINCIPAL: identitas utama agen yang memanggil server MCP. Contoh, serviceAccount:my-agent@my-project.iam.iam.gserviceaccount.com.
REGION: region Google Cloud tempat server MCP di-deploy.

Setelah memberikan peran run.invoker, agen yang memanggil dapat mengambil token identitas seperti yang dijelaskan di bagian Opsi validasi token.

Untuk mempelajari cara melindungi server MCP dengan IAP untuk CLI dan akses SDK terprogram, lihat Mengautentikasi server MCP.

Mengautentikasi atas nama pengguna

Saat mengakses alat dan layanan eksternal atas nama pengguna, agen Anda dapat menggunakan identitas agen yang disediakan untuk mengelola autentikasi dengan server MCP dan endpoint eksternal.

Untuk menangani alur kerja otorisasi yang kompleks secara aman, seperti persetujuan OAuth 3-legged (3LO), OAuth 2-legged (2LO), dan kunci API, konfigurasi Agent Identity Auth Manager.

Untuk mengetahui petunjuk tentang cara mengikat pengelola autentikasi ini ke toolset Anda, lihat Mengautentikasi ke alat dan resource.