Apa itu token akses beban kerja?Bagaimana Runtime dan Gateway secara otomatis mendapatkan token Cara mengambil token akses beban kerja secara manual Kontrol keamanan untuk GetWorkloadAccessTokenForUserIdAPI

Dapatkan token akses beban kerja

Memahami apa itu token akses beban kerja, cara mendapatkannya, dan aspek keamanan bekerja dengannya sangat penting untuk membangun aplikasi agen yang aman. Bagian ini mencakup konsep kunci dan pola implementasi yang perlu Anda ketahui.

Topik

Apa itu token akses beban kerja?
Bagaimana Runtime dan Gateway secara otomatis mendapatkan token
Cara mengambil token akses beban kerja secara manual
Kontrol keamanan untuk GetWorkloadAccessTokenForUserIdAPI

Apa itu token akses beban kerja?

Token akses beban kerja adalah token akses buram AWS bertanda tangan yang memungkinkan agen mengakses AgentCore layanan pihak pertama, seperti penyedia kredensi keluar. Runtime secara otomatis mengirimkan token akses beban kerja ke instance eksekusi agen sebagai header payload, menghilangkan kebutuhan akan manajemen token manual di sebagian besar skenario.

Karakteristik utama

First-party Hanya layanan — Token akses beban kerja khusus untuk mengakses AgentCore layanan AWS pihak pertama dan tidak dapat digunakan untuk layanan eksternal
Pengiriman otomatis - Runtime dan Gateway secara otomatis memberikan token ini kepada agen selama eksekusi
Keamanan berdasarkan desain - identitas Runtime-managed agen tidak dapat mengambil token akses beban kerja secara langsung, mencegah ekstraksi dan penyalahgunaan token
Pengikatan identitas pengguna dan agen — Token berisi identitas pengguna dan informasi identitas agen untuk akses kredensi yang aman

Bagaimana Runtime dan Gateway secara otomatis mendapatkan token

Ketika agen dipanggil melalui AgentCore Runtime atau Gateway dengan otentikasi masuk, layanan secara otomatis menangani pembuatan token akses beban kerja:

Runtime memvalidasi token OAuth penyedia identitas masuk (penerbit, tanda tangan)
Runtime mengekstrak penerbit dan sub klaim dari token OAuth yang mewakili identitas pengguna
Runtime mengambil identitas beban kerja terkait agen
Runtime memanggil GetWorkloadAccessTokenForJWT dengan identitas pengguna dan identitas beban kerja agen
Runtime meneruskan token akses beban kerja ke kode agen sebagai bagian dari header payload pemanggilan

Proses otomatis ini memastikan agen menerima token dengan cakupan yang benar tanpa intervensi manual.

Cara mengambil token akses beban kerja secara manual

Ada dua pola yang digunakan untuk mengambil token akses beban kerja tergantung pada bagaimana Anda dapat mengidentifikasi pengguna akhir agen:

Pola 1: JWT-based identifikasi (direkomendasikan untuk produksi)

Jika penelepon agen memiliki JWT yang dikeluarkan oleh penyedia identitas untuk pengguna akhir, mintalah token akses beban kerja menggunakan. GetWorkloadAccessTokenForJWT Saat Anda memberikan JWT, AgentCore Identity memvalidasi token untuk memastikannya ditandatangani dengan benar dan belum kedaluwarsa, dan menggunakan klaim “iss” dan “sub” untuk mengidentifikasi pengguna secara unik. Kredensil yang disimpan oleh agen atas nama pengguna dikaitkan dengan identitas yang diverifikasi secara kriptografi ini, dan pengambilan masa depan memerlukan token akses beban kerja yang valid yang membawa identitas yang sama.

Gunakan pola ini ketika:

Aplikasi Anda terintegrasi dengan penyedia identitas (Cognito, Auth0, Okta, dll.)
Anda memerlukan bukti kriptografi identitas pengguna akhir
Anda menyebarkan ke produksi

Pola 2: UserId-based identifikasi

Jika penelepon agen tidak memiliki JWT yang mengidentifikasi pengguna akhir, minta token akses beban kerja menggunakan string unik GetWorkloadAccessTokenForUserId yang mengidentifikasi pengguna.

Gunakan pola ini ketika:

Aplikasi Anda mengelola pengenal penggunanya sendiri dan Anda harus meneruskan string userId yang dikelola pelanggan ke Identity AgentCore
Anda berada dalam skenario pengembangan atau mulai cepat di mana token IDP belum tersedia
Arsitektur perusahaan Anda menyelesaikan identitas pengguna di hulu dan meneruskan pengenal tepercaya ke beban kerja agen

Tradeoff: Platform memperlakukan userID sebagai string buram dan tidak dapat memverifikasinya terhadap identitas pengguna akhir yang diautentikasi. Pengikatan keamanan bergantung pada beban kerja panggilan yang meneruskan userID yang benar dan kebijakan IAM yang dicakup dengan tepat. Lihat Kontrol keamanan untuk GetWorkloadAccessTokenForUserIdAPI untuk kontrol yang direkomendasikan.

Contoh kode

Contoh di bawah ini menggambarkan penggunaan AgentCore SDK untuk mengambil token akses beban kerja menggunakan dua metode ini:


from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

Kontrol keamanan untuk `GetWorkloadAccessTokenForUserId`API

GetWorkloadAccessTokenForUserIdAPI menerima string pengenal pengguna yang disediakan pemanggil dan mengeluarkan token akses beban kerja yang dicakup oleh pasangan agen pengguna tersebut. API ini dirancang untuk mendukung pelanggan perusahaan yang perlu meneruskan string userID yang dikelola pelanggan dan pembangun yang tidak memiliki token Penyedia Identitas (IDP) yang tersedia selama pengembangan.

penting

Saat Anda menggunakanGetWorkloadAccessTokenForUserId, platform memperlakukan userId nilai sebagai string buram dan tidak memverifikasinya terhadap identitas pengguna akhir yang diautentikasi. Pengikatan keamanan sepenuhnya bergantung pada beban kerja panggilan yang meneruskan userID yang benar dan kebijakan IAM Anda dicakup dengan tepat. Jika aplikasi Anda memiliki akses ke JWT yang mengidentifikasi pengguna akhir, gunakan GetWorkloadAccessTokenForJWT sebagai gantinya, yang memvalidasi penerbit token, tanda tangan, dan kedaluwarsa sebelum mengeluarkan token akses beban kerja.

GetWorkloadAccessTokenForUserIdAPI mengimplementasikan beberapa kontrol keamanan untuk mencegah akses yang tidak sah:

Validasi identitas beban kerja - API memverifikasi bahwa identitas yang meminta memiliki izin untuk bertindak atas nama identitas beban kerja yang ditentukan
Service-managed pembatasan identitas — Runtime-managed dan identitas Gateway-managed beban kerja tidak dapat mengambil token secara langsung. Ini mencegah agen mengekstraksi token untuk penyalahgunaan
Persyaratan izin IAM — Penelepon harus memiliki izin IAM yang sesuai termasuk,, dan GetWorkloadAccessToken GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT
Token cakupan — Token dicakup ke pasangan agen pengguna tertentu, memastikan kredensyal yang disimpan di bawah satu pengguna tidak dapat diakses oleh pengguna lain
Partisi ID Pengguna untuk beberapa penyedia identitas — Saat menggunakan beberapa penyedia identitas, partisi ID pengguna Anda menggunakan pola provider_id+user_id untuk mencegah tabrakan pengguna di antara penyedia yang berbeda. Misalnya, gunakan cognito+user123 dan auth0+user123 untuk membedakan pengguna dengan pengenal yang sama di berbagai penyedia identitas

Kontrol keamanan yang disarankan

Karena platform tidak dapat memverifikasi string userID, Anda bertanggung jawab untuk memastikan integritas nilai yang diteruskan ke API ini. Terapkan kontrol berikut:

Lebih suka GetWorkloadAccessTokenForJWT ketika JWT tersedia — JWT-based Jalur memvalidasi penerbit dan tanda tangan token, memberikan bukti kriptografi identitas pengguna. Gunakan GetWorkloadAccessTokenForUserId hanya jika JWT tidak tersedia.
Turunkan userID dari sumber tepercaya — Nilai userID harus diturunkan dari konteks prinsipal yang diautentikasi (misalnya, identitas pemanggil IAM, atribut sesi, atau lapisan resolusi identitas hulu) daripada menerima nilai yang disediakan klien sewenang-wenang. Ini mencegah penelepon yang diautentikasi meniru pengguna lain.
Batasi izin IAM — Hanya kepala sekolah tepercaya yang harus memiliki izin. bedrock-agentcore:GetWorkloadAccessTokenForUserId Cakupan izin ini ke sumber daya identitas beban kerja tertentu. Jangan berikan secara luas melalui kebijakan terkelola atau pernyataan sumber daya wildcard.

Tolak GetWorkloadAccessTokenForUserId di tempat yang tidak diperlukan - Untuk beban kerja yang selalu memiliki JWT tersedia, tolak secara eksplisit tindakan dalam kebijakan IAM untuk mencegah jalur userId digunakan:


{
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

Implementasikan audit logging - Log hubungan antara prinsipal IAM yang diautentikasi dan nilai userID yang diteruskan. Gunakan AWS CloudTrail untuk memantau GetWorkloadAccessTokenForUserId panggilan dan mendeteksi nilai userID yang tidak terduga.

Jika Anda menemukan kesalahan "WorkloadIdentity ditautkan ke layanan dan tidak dapat mengambil token akses oleh pemanggil,” ini menunjukkan identitas beban kerja dikelola oleh Runtime atau Gateway dan tidak dapat mengambil token secara langsung. Pembatasan ini membantu menjaga batas keamanan dan mencegah akses token yang tidak sah.

Untuk kontrol keamanan tambahan, Anda dapat menerapkan kebijakan akses berbutir halus untuk membatasi identitas beban kerja mana yang dapat mengakses penyedia kredensi tertentu. Untuk informasi selengkapnya, lihat Cakupan ke bawah akses ke penyedia kredensyal berdasarkan identitas beban kerja.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Dapatkan kredensi

Dapatkan token akses