Melakukan autentikasi ke layanan eksternal menggunakan identitas agen sendiri

Identitas Agen memungkinkan agen Anda di Google Cloud menggunakan identitas mereka sendiri untuk melakukan autentikasi ke layanan eksternal dan ke workload yang dihosting di Cloud Run atau Google Kubernetes Engine (GKE). Dengan menggunakan token ID OpenID Connect (OIDC), Anda dapat menghubungkan agen ke platform cloud pihak ketiga seperti Amazon Web Services (AWS) dan Microsoft Azure, API kustom, gateway API, dan backend lokal.

Saat agen bertindak atas otoritasnya sendiri, Agent Identity akan menerbitkan token ID OIDC, yang merupakan Token Web JSON (JWT) yang menyatakan identitas SPIFFE agen dan ditandatangani oleh kunci penerbit untuk domain kepercayaan agen (workload identity pool terkelola). Sistem eksternal dapat memverifikasi token ID ini tanpa Google Cloud kredensial atau SDK melalui endpoint publik yang dihosting oleh Google Cloud Layanan Token Keamanan:

  • Endpoint OpenID Connect Discovery 1.0 (/.well-known/openid-configuration) yang memublikasikan metadata penyedia OpenID dan endpoint kunci publik (jwks_uri).
  • Endpoint JSON Web Key Set (JWKS) (/openid/jwks) yang menyajikan kunci publik aktif yang digunakan untuk memverifikasi tanda tangan pada token ID agen.

Untuk mengautentikasi agen Anda ke API dan resource Google Cloud menggunakan identitasnya sendiri, lihat Mengautentikasi ke Google Cloud menggunakan identitas agen sendiri. Untuk mengakses layanan atas nama pengguna akhir, lihat Melakukan autentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi.

Sebelum memulai

  1. Pastikan Anda telah memilih metode autentikasi yang benar. Tinjau cara kerja identitas SPIFFE, domain kepercayaan, dan kredensial agen dalam Ringkasan Identitas Agen.
  2. Buat dan deploy agen dengan Agent Identity diaktifkan.

  3. Pastikan layanan atau penyedia identitas eksternal Anda memenuhi persyaratan berikut:

  4. Identifikasi nilai konfigurasi berikut untuk agen dan layanan eksternal target Anda:

    • URL Penerbit (klaim iss): URL penerbit workload identity pool untuk organisasi (https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN) atau project (https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN) Anda.
    • Audiens yang diizinkan (klaim aud): URI audiens yang diharapkan oleh layanan eksternal atau penyedia identitas saat memvalidasi token ID.

  5. Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk men-deploy agen dengan Agent Identity, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

  • Men-deploy agen ke Agent Runtime di Gemini Enterprise Agent Platform: Vertex AI User (roles/aiplatform.user)
  • Men-deploy layanan agen ke Cloud Run: Cloud Run Admin (roles/run.admin)

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

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk men-deploy agen dengan Agent Identity. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk men-deploy agen dengan Agent Identity:

  • Deploy agen ke Agent Runtime di Gemini Enterprise Agent Platform:
    • aiplatform.reasoningEngines.create
    • aiplatform.reasoningEngines.update
  • Men-deploy layanan agen ke Cloud Run:
    • run.services.create
    • run.services.update

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mendapatkan token ID OIDC untuk agen

Untuk mengonfigurasi agen Anda agar mendapatkan dan mengirim token ID OIDC ke layanan eksternal, selesaikan tugas-tugas berikut:

  1. Mengonfigurasi agen dengan Identitas Agen
  2. Meminta token ID OIDC dalam kode aplikasi

Mengonfigurasi agen Anda dengan Agent Identity

Aktifkan Agent Identity saat Anda men-deploy agen:

  • Jika Anda men-deploy agen ke Agent Runtime di Gemini Enterprise Agent Platform , tetapkan identity_type ke AGENT_IDENTITY:

    remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

  • Jika Anda men-deploy layanan agen dalam container ke Cloud Run, teruskan flag --identity-type=agent-identity:

    gcloud run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --identity-type=agent-identity \
    --no-allow-unauthenticated

    Ganti kode berikut:

    • SERVICE_NAME: Nama layanan Cloud Run Anda.
    • IMAGE_URL: URL image container untuk agen Anda.

Meminta token ID OIDC dalam kode aplikasi

Dalam kode aplikasi agen Anda, gunakan library klien Google Auth untuk meminta token ID OIDC bagi audiens eksternal target Anda. Library klien menangani pembuatan token, caching lokal, dan perpanjangan otomatis dari server metadata.

Secara default, library klien Google Auth yang didukung mengikat token ID OIDC secara kriptografis ke sertifikat X.509 unik agen dengan menyertakan sidik jari sertifikat dalam klaim cnf (x5t#S256) token. Layanan penerima dapat memvalidasi klaim ini secara opsional terhadap sertifikat klien yang ditampilkan selama handshake mutual TLS (mTLS), atau mengabaikan klaim jika tidak menerapkan pengikatan sertifikat.

Cloud Run otomatis menerapkan pengikatan sertifikat saat klaim cnf ada dalam token ID. Jika agen Anda memanggil layanan Cloud Run menggunakan token ID terikat, Anda harus memanggil endpoint mTLS-nya (*.mtls.run.app) melalui koneksi mTLS. Untuk terus memanggil URL *.run.app standar, pilih tidak ikut pengikatan sertifikat per permintaan (misalnya, dengan menetapkan bind_id_token=False di Python) atau di seluruh lingkungan runtime dengan GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false. Untuk versi library dan contoh yang didukung, lihat Memilih tidak menggunakan token terikat sertifikat.

Saat memanggil endpoint yang menerapkan pengikatan sertifikat melalui mTLS, konfigurasikan sesi klien untuk menampilkan sertifikat X.509 agen selama handshake mTLS (misalnya, dengan memanggil authed_session.configure_mtls_channel() di Python).

Contoh berikut menggunakan library google-auth untuk meminta token ID OIDC yang terikat sertifikat, mengonfigurasi saluran mTLS secara opsional, dan melampirkan token sebagai token Bearer dalam permintaan keluar:

Python

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import id_token

# 1. Specify the audience expected by the external receiver
# (for example, AWS Bedrock AgentCore or your external service URL).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create ID token credentials and an AuthorizedSession, which handles
# local token caching, automatic renewal before expiry, and the
# Bearer header.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)

# 3. Send the authenticated request to the external service.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

Ganti kode berikut:

  • EXTERNAL_SERVICE_AUDIENCE: URI audiens yang diharapkan oleh layanan penerima Anda (misalnya, bedrock.us-east-1.amazonaws.com atau api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: URL API eksternal atau endpoint backend yang dipanggil agen Anda.

Python (mTLS)

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import id_token

# 1. Specify the audience expected by the receiving service
# (for example, a regional Cloud Run mTLS URL or an on-premises mTLS endpoint).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create certificate-bound ID token credentials and configure the mTLS
# channel to present the agent's X.509 certificate.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)
authed_session.configure_mtls_channel()

# 3. Send the authenticated request over mTLS.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

Ganti kode berikut:

  • EXTERNAL_SERVICE_AUDIENCE: URI audiens yang diharapkan oleh layanan penerima Anda (misalnya, URL mTLS Cloud Run regional atau api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: URL endpoint backend atau API mTLS yang dipanggil agen Anda.

Untuk petunjuk dan contoh library klien dalam bahasa lain, seperti Go, Node.js, dan Java, lihat Mendapatkan token ID. Library klien untuk bahasa ini mendukung --identity-type=agent-identity. Library yang mendukung token ID terikat sertifikat akan mengikat token secara default dan memungkinkan Anda memilih tidak ikut untuk setiap permintaan.

Memverifikasi token ID Agent Identity

Saat layanan eksternal menerima token ID OIDC dari agen Anda, verifikasi token tersebut menggunakan salah satu pendekatan berikut berdasarkan layanan target:

Menggunakan workload identity federation bawaan

Jika layanan penerima Anda berjalan di platform cloud yang mendukung autentikasi IAM bawaan atau workload identity federation OIDC, Anda tidak perlu menulis kode verifikasi token kustom:

  • Cloud Run: Jika layanan penerima Anda berjalan di Cloud Run dengan ingress yang diautentikasi (--no-allow-unauthenticated), Cloud Run akan memvalidasi token Agent Identity yang masuk di lapisan ingress. Jika token menyertakan klaim cnf, konfigurasikan agen panggilan untuk menargetkan URL mTLS regional layanan penerima (https://SERVICE_NAME-PROJECT_NUMBER.REGION.mtls.run.app) agar Cloud Run dapat memvalidasi sertifikat klien selama handshake mTLS. Berikan peran Cloud Run Invoker (roles/run.invoker) kepada agen panggilan di layanan penerima. Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi ke server MCP di Cloud Run.

    Jika layanan Anda mengizinkan ingress yang tidak diautentikasi dan memverifikasi token dalam kode aplikasi, lihat Memverifikasi token secara terprogram.

  • Amazon Bedrock: Konfigurasi autentikasi JWT masuk dengan menentukan URL penemuan atau URL penerbit Google Cloud Security Token Service dan audiens yang Anda harapkan. Untuk mengetahui petunjuknya, lihat Mengonfigurasi pemberi otorisasi JWT masuk dalam dokumentasi AWS.

  • Microsoft Entra ID: Konfigurasi kredensial identitas gabungan dengan skenario Other issuer. Tentukan URL penerbit Google Cloud Security Token Service, audiens yang diharapkan, dan ID subjek (klaim sub). Untuk mengetahui petunjuknya, lihat Membuat hubungan kepercayaan antara aplikasi dan penyedia identitas eksternal dalam dokumentasi Microsoft Learn.

Memverifikasi token secara terprogram

Jika agen Anda mengirim permintaan ke API kustom, microservice, gateway API, atau workload lokal, layanan penerima Anda harus memverifikasi token ID OIDC yang masuk sebelum memberikan akses. Agen Anda biasanya meneruskan token ini di header HTTP Authorization: Bearer TOKEN.

Untuk memverifikasi token ID yang masuk secara terprogram, selesaikan tugas berikut:

  1. Mengekstrak dan memvalidasi URL penerbit token
  2. Menemukan dan meng-cache kunci penandatanganan publik
  3. Memverifikasi tanda tangan dan klaim token
  4. Opsional: Memvalidasi binding sertifikat (klaim cnf)
  5. Memberikan otorisasi identitas SPIFFE agen

Mengekstrak dan memvalidasi URL penerbit token

Saat permintaan masuk tiba, baca payload JWT yang belum diverifikasi untuk mengekstrak klaim iss (penerbit). Klaim ini berisi URL workload identity pool untuk domain trust agen. URL ini berfungsi sebagai URL dasar untuk dokumen discovery dan kunci penandatanganan publik.

Sebelum membuat permintaan jaringan keluar, pastikan klaim iss cocok dengan URL workload identity pool Security Token Service Google Cloud yang diharapkan untuk organisasi atau project Anda:

  • Domain kepercayaan tingkat organisasi:

    https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Misalnya, untuk organisasi dengan ID 123456789012, TRUST_DOMAIN adalah agents.global.org-123456789012.system.id.goog.

  • Domain trust level project (untuk project tanpa organisasi):

    https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Misalnya, untuk project dengan nomor 9876543210, TRUST_DOMAIN adalah agents.global.proj-9876543210.system.id.goog.

Menemukan dan meng-cache kunci penandatanganan publik

Setelah Anda memvalidasi URL penerbit, ambil dan simpan kunci penandatanganan publik ke dalam cache dari Google Cloud Security Token Service:

  1. Buat kueri endpoint OpenID Connect Discovery: Tambahkan /.well-known/openid-configuration ke URL penerbit dasar dan kirim permintaan GET HTTP yang tidak diautentikasi:

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • ORGANIZATION_ID: ID organisasi Google Cloud Anda. Untuk project tanpa organisasi, ganti organizations/ORGANIZATION_ID dengan projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: ID workload identity pool untuk domain tepercaya agen Anda (misalnya, agents.global.org-123456789012.system.id.goog).

    Metode HTTP dan URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Permintaan yang berhasil akan menampilkan status HTTP 200 OK dan objek JSON yang berisi metadata Penyedia OpenID, termasuk kolom jwks_uri:

    {
  "issuer": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog",
  "jwks_uri": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/openid/jwks",
  "authorization_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/authorize",
  "token_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/token",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

  2. Buat kueri endpoint JSON Web Key Set (JWKS): Kirim permintaan GET HTTP yang tidak diautentikasi ke URL jwks_uri yang ditampilkan dalam metadata Penyedia OpenID:

    Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

    • ORGANIZATION_ID: ID organisasi Google Cloud Anda. Untuk project tanpa organisasi, ganti organizations/ORGANIZATION_ID dengan projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: ID workload identity pool untuk domain tepercaya agen Anda (misalnya, agents.global.org-123456789012.system.id.goog).

    Metode HTTP dan URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks

    Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

    Permintaan yang berhasil akan menampilkan status HTTP 200 OK dan objek JSON yang berisi array kunci publik yang diformat sesuai dengan RFC 7517:

    {
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "4d1933f8e6c4e0b512c140989f6655c68997...",
      "n": "uQn4zN_1mQ0VpGv82-Wp3w...",
      "e": "AQAB"
    }
  ]
}

  3. Cache dokumen discovery dan kunci: Respons dari endpoint OpenID Connect Discovery dan endpoint JWKS menyertakan header cache HTTP berikut:

    Cache-Control: public, max-age=86400, must-revalidate

    Men-cache dokumen discovery dan JWKS hingga 24 jam (86400 detik) untuk meningkatkan performa verifikasi dan menghindari pembatasan kapasitas.

    Google Cloud secara berkala merotasi kunci penandatanganan pribadi dan publik untuk workload identity pool. Jika pemverifikasi Anda menerima token masuk dengan kid (ID kunci) yang tidak ada dalam cache kunci lokalnya, ambil JWKS baru dari endpoint /openid/jwks sebelum menolak token.

    Jika Anda mengalami error HTTP saat mengkueri endpoint penemuan atau JWKS, lihat Memecahkan masalah autentikasi Agent Identity.

Memverifikasi tanda tangan dan klaim token

Untuk memverifikasi tanda tangan token secara kriptografis dan memvalidasi klaim JWT, gunakan library verifikasi OIDC atau JWT standar (seperti Google Tink) dan lakukan hal berikut:

  1. Tanda tangan: Temukan kunci publik di JWKS yang di-cache yang cocok dengan kid (ID kunci) di header JWT. Validasi tanda tangan menggunakan algoritma yang ditentukan di kolom alg (RS256). Untuk kompatibilitas ke depan, periksa kolom alg dan kty di JWKS secara dinamis, bukan melakukan hardcode pada jenis algoritma.
  2. Issuer (iss): Pastikan klaim iss cocok dengan URL penerbit workload identity poolGoogle Cloud tepercaya untuk domain kepercayaan Anda.
  3. Audiens (aud): Pastikan klaim aud cocok dengan ID audiens yang dikonfigurasi layanan Anda.
  4. Waktu penerbitan (iat) dan waktu habis masa berlaku (exp): Pastikan klaim iat berada di masa lalu dan waktu saat ini lebih awal dari klaim exp (memungkinkan toleransi perbedaan waktu yang kecil, seperti 1 hingga 2 menit).

Contoh berikut menggunakan Google Tink (tink.jwt) untuk memverifikasi token ID Agent Identity terhadap payload JSON JWKS:

Python

import tink
from tink import jwt

# Initialize Tink JWT signature primitives (call once at application startup).
jwt.register_jwt_signature()


def verify_agent_identity_token(
    token: str,
    jwks_json: str,
    expected_issuer: str,
    expected_audience: str,
) -> jwt.VerifiedJwt:
    """Verifies an Agent Identity JWT against a JWKS JSON string using Tink.

    Args:
        token: The compact serialized JWT string.
        jwks_json: The JWKS JSON string fetched from the STS pool endpoint.
        expected_issuer: The expected token issuer ('iss' claim).
        expected_audience: The expected token audience ('aud' claim).

    Returns:
        jwt.VerifiedJwt: The verified JWT claims object.

    Raises:
        tink.TinkError: If the JWKS cannot be parsed, the key is not found,
            or token validation (signature, issuer, audience, expiration) fails.
    """
    # 1. Convert the JWKS JSON into a Tink public KeysetHandle.
    keyset_handle = jwt.jwk_set_to_public_keyset_handle(jwks_json)

    # 2. Instantiate the Tink JwtPublicKeyVerify primitive.
    jwt_verifier = keyset_handle.primitive(jwt.JwtPublicKeyVerify)

    # 3. Configure expected validation rules (issuer, audience, expiration).
    # Google Cloud STS sets 'typ': 'JWT' in the header, so
    # expected_type_header="JWT" is required.
    validator = jwt.new_validator(
        expected_issuer=expected_issuer,
        expected_audience=expected_audience,
        expected_type_header="JWT",
        allow_missing_expiration=False,
    )

    # 4. Cryptographically verify the signature and standard OIDC claims.
    return jwt_verifier.verify_and_decode(token, validator)

Opsional: Memvalidasi binding sertifikat (klaim cnf)

Jika layanan penerima Anda menerapkan pengikatan sertifikat melalui mTLS, validasi klaim cnf (x5t#S256) terhadap sertifikat klien yang ditampilkan selama handshake mTLS:

  1. Hentikan mutual TLS (mTLS): Konfigurasikan server atau proxy ingress Anda untuk meminta dan memvalidasi sertifikat X.509 agen selama TLS handshake sesuai dengan TLS 1.3 (RFC 9846).
  2. Menghitung sidik jari sertifikat (x5t#S256): Ekstrak sertifikat klien X.509 leaf dari koneksi mTLS. Hitung hash SHA-256 pada byte berenkode DER, dan enkode base64url digest tanpa padding =.
  3. Validasi klaim cnf (x5t#S256): Periksa payload JWT yang diverifikasi untuk objek cnf ({"cnf": {"x5t#S256": "FINGERPRINT"}}) dan verifikasi bahwa nilai x5t#S256 cocok dengan sidik jari sertifikat klien sesuai dengan RFC 8705 Bagian 6.1. Jika pemanggil tidak memberikan sertifikat klien melalui mTLS atau jika sidik jari tidak cocok, tolak permintaan dengan respons HTTP 401 Unauthorized.

Memberikan otorisasi pada identitas SPIFFE agen

Setelah Anda memverifikasi tanda tangan token dan klaim standar, periksa klaim sub (subjek) yang diverifikasi untuk mengizinkan permintaan dan mencatat agen panggilan dalam log audit Anda.

Klaim sub berisi ID SPIFFE unik agen, misalnya:

  spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent

Dalam logika otorisasi layanan Anda, bandingkan klaim sub yang diverifikasi dengan daftar yang diizinkan dari ID SPIFFE agen tepercaya (atau awalan domain kepercayaan) sebelum memberikan akses ke resource yang dilindungi.

Langkah berikutnya