Melakukan autentikasi ke layanan eksternal menggunakan identitas agen sendiri

Pratinjau

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Agen yang dihosting di Google Cloud dapat menggunakan identitasnya sendiri untuk mengautentikasi alat dan layanan yang dihosting di runtime Google Cloud , seperti Cloud Run atau Google Kubernetes Engine (GKE), dengan meminta token ID OpenID Connect (OIDC) dari Agent Identity. Agen juga dapat menggunakan token ID ini untuk mengautentikasi 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 untuk mengakses layanan eksternal, Agent Identity akan menerbitkan token ID OpenID Connect (OIDC). Token Web JSON (JWT) ini menegaskan identitas SPIFFE agen dan ditandatangani oleh kunci penerbit untuk domain tepercaya agen (kumpulan identitas workload terkelola). Sistem eksternal dapat memverifikasi token ini tanpa kredensial Google Cloud atau SDK melalui endpoint publik yang dihosting oleh Google Cloud Security Token Service:

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

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

Sebelum memulai

1. Verifikasi bahwa Anda telah memilih metode autentikasi yang benar. Tinjau cara kerja identitas SPIFFE, domain tepercaya, dan kredensial agen dalam ringkasan Identitas Agen.
2. Buat dan deploy agen dengan Identitas Agen diaktifkan.
3. Pastikan layanan eksternal atau penyedia identitas Anda memenuhi persyaratan berikut:
   • Mendukung validasi Token Web JSON (JWT) menggunakan Penemuan OpenID Connect 1.0 dan JSON Web Key Set (JWKS).
   • Dapat mengirim permintaan HTTPS keluar ke https://sts.googleapis.com untuk mengambil metadata Penyedia OpenID dan kunci penandatanganan publik.
4. Identifikasi nilai konfigurasi berikut untuk agen dan target layanan eksternal 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 penyedia identitas atau layanan eksternal saat memvalidasi token ID.
5. Pastikan Anda memiliki peran yang diperlukan untuk menyelesaikan tugas ini.

Peran yang diperlukan

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

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

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

Peran bawaan ini berisi izin yang diperlukan untuk men-deploy agen dengan Identitas Agen. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk men-deploy agen dengan Identitas Agen:

• Men-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.

Catatan: Layanan eksternal dan pemverifikasi pihak ketiga tidak memerlukan peran IAM atau kredensial Google Cloud apa pun untuk memverifikasi token ID OIDC yang dikeluarkan oleh Agent Identity. Endpoint OpenID Connect Discovery (/.well-known/openid-configuration) dan Kumpulan Kunci Web JSON (/openid/jwks) bersifat publik dan tidak diautentikasi.

Mendapatkan token ID OIDC untuk agen

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

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

Mengonfigurasi agen Anda dengan Identitas Agen

Aktifkan Identitas Agen 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 tanda --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 untuk audiens eksternal target Anda. Library klien menangani pembuatan token, caching lokal, dan perpanjangan otomatis dari server metadata.

Secara default, token ID OIDC yang dikeluarkan untuk audiens eksternal tidak terikat ke sertifikat runtime.

Contoh berikut menggunakan library google-auth untuk meminta token ID OIDC dan melampirkannya 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 endpoint API eksternal atau backend yang dipanggil agen Anda.

Untuk mengetahui petunjuk dan contoh library klien dalam bahasa pemrograman lain (termasuk Go, Node.js, dan Java), lihat Mendapatkan token ID. Versi library klien saat ini untuk bahasa ini mendukung --identity-type=agent-identity, tetapi tidak menggunakan token terikat secara default.

Memverifikasi token ID Identitas Agen

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

• Platform cloud terkelola (seperti Cloud Run, AWS, atau Microsoft Azure): Gunakan workload identity federation bawaan untuk memverifikasi token masuk tanpa menulis kode verifikasi kustom.
• Layanan backend kustom, gateway API, dan beban kerja lokal: Verifikasi token secara terprogram menggunakan endpoint JWKS dan Penemuan OpenID Connect publik.

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 terautentikasi (--no-allow-unauthenticated), Cloud Run akan memvalidasi token Identitas Agen yang masuk di lapisan ingress. Berikan agen panggilan peran Cloud Run Invoker (roles/run.invoker) pada layanan penerima. Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi 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 Google Cloud URL penemuan layanan atau URL penerbit Security Token Service dan audiens yang diharapkan. Untuk mengetahui petunjuknya, lihat Mengonfigurasi pemberi otorisasi JWT masuk dalam dokumentasi AWS.

• Microsoft Entra ID: Konfigurasi kredensial identitas gabungan dengan skenario Penerbit lainnya. Tentukan URL penerbit Google Cloud Security Token Service yang diharapkan, audiens, 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 masuk secara terprogram, selesaikan tugas berikut:

1. Ekstrak dan validasi URL penerbit token
2. Menemukan dan menyimpan kunci penandatanganan publik dalam cache
3. Memverifikasi tanda tangan dan klaim token
4. 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 tepercaya agen. URL ini berfungsi sebagai URL dasar untuk dokumen discovery dan kunci penandatanganan publik.

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

• Domain tepercaya 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 tepercaya tingkat 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.

Perhatian: Selalu validasi bahwa URL iss diawali dengan https://sts.googleapis.com/v1/ dan termasuk dalam organisasi atau project Google Cloud yang tepercaya sebelum mengirim permintaan HTTP ke endpoint penemuan.

Menemukan dan menyimpan dalam cache kunci penandatanganan publik

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

1. Kueri endpoint Penemuan OpenID Connect: Tambahkan /.well-known/openid-configuration ke URL penerbit dasar dan kirim permintaan HTTP GET 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:

   curl (Linux, macOS, atau Cloud Shell)

   Jalankan perintah berikut:

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

   PowerShell (Windows)

   Jalankan perintah berikut:

   $headers = @{  }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration" | Select-Object -Expand Content

   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. Kueri endpoint JSON Web Key Set (JWKS): Kirim permintaan HTTP GET 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:

   curl (Linux, macOS, atau Cloud Shell)

   Jalankan perintah berikut:

   curl -X GET \
        "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks"

   PowerShell (Windows)

   Jalankan perintah berikut:

   $headers = @{  }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks" | Select-Object -Expand Content

   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 Penemuan OpenID Connect dan endpoint JWKS mencakup header cache HTTP berikut:

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

   Simpan dalam cache dokumen discovery dan JWKS hingga 24 jam (86400 detik) untuk meningkatkan performa verifikasi dan menghindari pembatasan kecepatan.

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

   Jika Anda mengalami error HTTP saat membuat kueri 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 JWT atau OIDC 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 dalam kolom alg (RS256). Untuk kompatibilitas ke depan, periksa kolom alg dan kty di JWKS secara dinamis, bukan meng-hardcode jenis algoritma.
2. Penerbit (iss): Pastikan klaim iss cocok dengan URL penerbit workload identity poolGoogle Cloud tepercaya untuk domain tepercaya 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): Verifikasi bahwa klaim iat berada di masa lalu dan waktu saat ini lebih awal dari klaim exp (dengan toleransi sedikit perbedaan waktu, 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)

Memberikan otorisasi pada identitas SPIFFE agen

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

Klaim sub berisi SPIFFE ID 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 terverifikasi dengan daftar yang diizinkan dari ID SPIFFE agen tepercaya (atau awalan domain tepercaya) sebelum memberikan akses ke resource yang dilindungi.

Langkah berikutnya

• Memecahkan masalah autentikasi Identitas Agen
• Mengautentikasi ke Google Cloud menggunakan identitas agen itu sendiri
• Mengautentikasi menggunakan 2-legged OAuth dengan pengelola autentikasi
• Mengautentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi
• Mengautentikasi menggunakan kunci API dengan pengelola autentikasi
• Ringkasan Identitas Agen