View a markdown version of this page

Dapatkan token akses beban kerja - Batu Dasar Amazon AgentCore
Apa itu token akses beban kerja?Bagaimana Runtime dan Gateway secara otomatis mendapatkan tokenCara mengambil token akses beban kerja secara manualKontrol keamanan untuk GetWorkloadAccessTokenForUserId API

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

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.

Apa itu token akses beban kerja?

Token akses beban kerja adalah token akses buram yang AWS ditandatangani yang memungkinkan agen mengakses AgentCore layanan pihak pertama, seperti penyedia kredensia keluar. Runtime secara otomatis mengirimkan token akses beban kerja ke instans eksekusi agen sebagai header muatan, menghilangkan kebutuhan untuk manajemen token manual di sebagian besar skenario.

Karakteristik utama

  • First-party layanan saja — 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 menyediakan token ini kepada agen selama eksekusi

  • Keamanan berdasarkan desain — identitas Runtime-managed agen tidak dapat mengambil token akses beban kerja secara langsung, mencegah ekstraksi token dan penyalahgunaan

  • 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:

  1. Runtime memvalidasi token OAuth penyedia identitas masuk (penerbit, tanda tangan)

  2. Runtime mengekstrak penerbit dan sub klaim dari token OAuth yang mewakili identitas pengguna

  3. Runtime mengambil identitas beban kerja yang terkait dari agen

  4. Runtime memanggil GetWorkloadAccessTokenForJWT dengan identitas pengguna dan identitas beban kerja agen

  5. 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, minta token akses beban kerja menggunakan. GetWorkloadAccessTokenForJWT Saat Anda memberikan JWT, AgentCore Identity memvalidasi token untuk memastikannya ditandatangani dengan benar dan tidak kedaluwarsa, dan menggunakan klaim “iss” dan “sub” untuk mengidentifikasi pengguna secara unik. KredenSIAL yang disimpan oleh agen atas nama pengguna dikaitkan dengan identitas yang diverifikasi secara kriptografis ini, dan pengambilan di masa mendatang 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 GetWorkloadAccessTokenForUserId string unik yang mengidentifikasi pengguna.

Gunakan pola ini ketika:

  • Aplikasi Anda mengelola pengidentifikasi penggunanya sendiri dan Anda perlu meneruskan string UserId yang dikelola pelanggan ke Identitas AgentCore

  • Anda berada dalam skenario pengembangan atau memulai 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 GetWorkloadAccessTokenForUserId API kontrol yang disarankan.

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 ke pasangan agen pengguna tersebut. API ini dirancang untuk mendukung pelanggan perusahaan yang perlu melewati string UserID yang dikelola pelanggan dan pembuat yang tidak memiliki token Penyedia Identity (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 sebagai GetWorkloadAccessTokenForJWT gantinya, yang memvalidasi penerbit token, tanda tangan, dan kedaluwarsa sebelum mengeluarkan token akses beban kerja.

GetWorkloadAccessTokenForUserIdAPI menerapkan beberapa kontrol keamanan untuk mencegah akses 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 termasukGetWorkloadAccessToken,, dan GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT

  • Pelingkupan token — Token dicakup ke pasangan agen pengguna tertentu, memastikan kredenSIAL 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 antara penyedia yang berbeda. Misalnya, gunakan cognito+user123 dan auth0+user123 membedakan pengguna dengan pengenal yang sama di seluruh penyedia identitas yang berbeda

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 secara arbitrer. Ini mencegah penelepon yang diautentikasi menyamar sebagai pengguna lain.

  • Batasi izin IAM — Hanya prinsipal tepercaya yang harus memiliki izin. bedrock-agentcore:GetWorkloadAccessTokenForUserId Cakup izin ini ke sumber daya identitas beban kerja tertentu. Jangan memberikannya secara luas melalui kebijakan terkelola atau pernyataan sumber daya wildcard.

  • Tol GetWorkloadAccessTokenForUserId ak jika 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"
      }
   ]
}

  • Menerapkan pencatatan audit — Catat 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 mengalami 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 halus untuk membatasi identitas beban kerja mana yang dapat mengakses penyedia kredensia tertentu. Untuk informasi selengkapnya, lihat Mengurangi akses ke penyedia kredensia berdasarkan identitas beban kerja.