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.

Mengautentikasi ke Google Cloud API, agen lain, dan alat

Saat workload Cloud Run Anda dikonfigurasi dengan jenis identitas agent-identity, workload 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 dengan aman saat berkomunikasi dengan Google Cloud API, agen lain, atau alat.

Mengautentikasi ke Google Cloud API

Agen dapat menggunakan identitas agen yang ditetapkan untuk mengautentikasi ke Google Cloud API seperti Vertex AI, Cloud Storage, dan Google Cloud produk 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 API Google Cloud lain:
  
  Berikan peran yang diperlukan pada resource target Anda ke AGENT_PRINCIPAL, misalnya, roles/storage.objectViewer di bucket Cloud Storage. Untuk mengetahui detailnya, lihat Mengautentikasi dengan Kredensial Default Aplikasi.
Ganti kode berikut:
- PROJECT_ID: ID project Anda Google Cloud .
- 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 Anda, gunakan library klien Google Cloud standar. Library klien akan otomatis menggunakan Kredensial Default Aplikasi (ADC) untuk mengambil token akses berumur pendek dari server metadata.

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

Mengautentikasi ke agen lain di Cloud Run

Jika 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 identitas agen pemanggil peran roles/run.invoker pada 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 pemanggil.
- REGION: Google Cloud region layanan target.

Opsi validasi token

Cloud Run mendukung dua metode validasi token identitas:

Token tidak terikat: token identitas terikat audiens standar yang dihasilkan 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 workload menggunakan mTLS. Untuk menggunakan token terikat, klien pemanggil memberikan rantai sertifikat leaf dalam permintaan.

Mengambil token ID tidak terikat

Dari dalam container agen pemanggil, 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 Authorization header:

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

Mengambil token ID terikat (mTLS)

Dari dalam container agen pemanggil, 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 jika 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 layanan Cloud Run tujuan, misalnya, https://target-agent-12345.us-central1.mtls.run.app.

Mengautentikasi 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 run 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. Misalnya, serviceAccount:my-agent@my-project.iam..
REGION: Google Cloud region tempat server MCP di-deploy.

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

Untuk mempelajari cara melindungi server MCP dengan IAP untuk akses CLI dan 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 dengan aman, seperti izin OAuth 3-legged (3LO), OAuth 2-legged (2LO), dan kunci API, konfigurasikan Pengelola Autentikasi Identitas Agen.

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