# Otentikasi dan otorisasi dengan Inbound Auth dan Outbound Auth
[Bagian ini menunjukkan cara menerapkan otentikasi dan otorisasi untuk runtime agen Anda menggunakan token pembawa OAuth dan JWT dengan Identity. AgentCore ](identity.md) Anda akan mempelajari cara mengatur kumpulan pengguna Cognito, mengonfigurasi runtime agen Anda untuk otentikasi JWT (Auth Masuk), dan menerapkan OAuth-based akses ke sumber daya pihak ketiga (Auth keluar).
Untuk contoh lengkapnya, lihat[https://github.com/awslabs/amazon-bedrock-agentcore-samples/](https://github.com/awslabs/amazon-bedrock-agentcore-samples/).
Untuk informasi tentang menggunakan OAuth dengan server MCP, lihat [Menerapkan](runtime-mcp.md) server MCP di Runtime. AgentCore
AgentCore Runtime Amazon Bedrock menyediakan dua mekanisme otentikasi untuk agen yang dihosting:
**Otentikasi IAM SiGv4**
Otentikasi default dan mekanisme otorisasi yang bekerja secara otomatis tanpa konfigurasi tambahan, mirip dengan API lainnya AWS .
**X-Amzn-Bedrock-AgentCore-Runtime-User-Id Header**
Jika solusi Anda mengharuskan agen yang dihosting untuk mengambil token OAuth atas nama pengguna akhir (menggunakan Pemberian Kode Otorisasi), Anda dapat menentukan pengenal pengguna dengan menyertakan header dalam `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` permintaan Anda. Header ini menggunakan `GetWorkloadAccessTokenForUserId` jalur secara internal.
Memanggil InvokeAgentRuntime dengan `X-Amzn-Bedrock-AgentCore-Runtime-User-Id header` akan membutuhkan tindakan IAM baru:`bedrock-agentcore:InvokeAgentRuntimeForUser`, selain tindakan yang ada`bedrock-agentcore:InvokeAgentRuntime`.
**Kapan menggunakan header ini versus otentikasi JWT Bearer Token**
Header ini dirancang untuk kasus penggunaan berikut:
+ **Pelanggan perusahaan dengan pengidentifikasi pengguna yang dikelola pelanggan —** Organizations yang memelihara string identitas pengguna mereka sendiri dan harus meneruskannya ke AgentCore Identity untuk mengikat kredensi.
+ **Skenario pengembangan dan mulai cepat** — Pembangun yang belum memiliki token IDP yang tersedia dan membutuhkan jalur cepat untuk menguji alur kredensi cakupan pengguna.
Untuk penerapan produksi di mana Anda memiliki penyedia identitas yang dikonfigurasi, gunakan otentikasi Token [JWT Bearer](#oauth-sample-overview) sebagai gantinya. Jalur JWT (`GetWorkloadAccessTokenForJWT`) memvalidasi penerbit token, tanda tangan, dan kedaluwarsa, memberikan bukti kriptografi identitas pengguna. Jalur `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` header tidak memverifikasi userID terhadap identitas pengguna akhir yang diautentikasi — ini bergantung pada beban kerja panggilan untuk meneruskan nilai yang benar dan pada kebijakan IAM Anda untuk membatasi siapa yang dapat menyediakannya.
**Praktik Terbaik Keamanan untuk X-Amzn-Bedrock-AgentCore-Runtime-User-Id Header**
**Tip**
Untuk tampilan gabungan dari semua rekomendasi keamanan Runtime, lihat [Praktik terbaik keamanan untuk AgentCore ](runtime-security-best-practices.md) Runtime.
Karena AgentCore memperlakukan nilai header sebagai pengidentifikasi buram tanpa memverifikasinya terhadap identitas yang diautentikasi, Anda harus menerapkan kontrol berikut untuk mempertahankan batas keamanan:
+ **Batasi izin IAM** — Hanya kepala sekolah tepercaya yang harus memiliki izin. `bedrock-agentcore:InvokeAgentRuntimeForUser` Cakupan izin ini ke sumber daya runtime tertentu menggunakan kondisi sumber daya IAM. Jangan berikan secara luas melalui kebijakan terkelola atau pernyataan sumber daya wildcard.
+ **Turunkan user-id dari prinsipal yang diautentikasi** — Nilai user-id harus diturunkan dari konteks prinsipal yang diautentikasi (misalnya, identitas pemanggil IAM atau klaim token pengguna) daripada menerima nilai yang disediakan klien sewenang-wenang. Ini mencegah pengguna yang diautentikasi meniru pengguna lain dengan secara manual menentukan yang berbeda. `user-id`
+ **Implementasikan audit logging** — Log hubungan antara prinsipal IAM yang diautentikasi (dari konteks SigV4) dan nilai yang `user-id` diteruskan. Gunakan AWS CloudTrail untuk memantau `InvokeAgentRuntime` panggilan yang menyertakan `runtimeUserId` parameter.
+ **Tolak header dalam konteks yang tidak tepercaya** — Untuk runtime di mana delegasi user-id tidak diperlukan, tolak secara eksplisit `bedrock-agentcore:InvokeAgentRuntimeForUser` tindakan dalam kebijakan IAM untuk mencegah header diterima:
```
{
"Statement": [
{
"Sid": "DenyUserIdDelegation",
"Effect": "Deny",
"Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
"Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
}
]
}
```
**Otentikasi Token Pembawa JWT**
Anda dapat mengonfigurasi runtime agen Anda untuk menerima token pembawa JWT dengan menyediakan konfigurasi otorisasi selama pembuatan agen.
Konfigurasi ini meliputi:
+ Discovery URL - String yang harus cocok dengan pola `^.+/\.well-known/openid-configuration$` untuk URL penemuan OpenID Connect
+ Audiens yang diizinkan - Daftar pemirsa yang diizinkan yang akan divalidasi terhadap klaim aud dalam token JWT
+ Klien yang diizinkan - Daftar pengidentifikasi klien yang diizinkan yang akan divalidasi terhadap klaim client\_id dalam token JWT
+ Cakupan yang diizinkan - Daftar cakupan yang diizinkan yang akan divalidasi terhadap klaim ruang lingkup dalam token JWT. Bidang `allowedScopes` otorisasi akan dikonfigurasi sebagai daftar string.
+ Klaim kustom wajib - Daftar klaim wajib yang akan divalidasi terhadap nama klaim dan nilai yang terkandung dalam token JWT yang masuk. Untuk detail tentang mengonfigurasi otorisasi, lihat [Mengonfigurasi otorisasi JWT masuk](inbound-jwt-authorizer.md)
**catatan**
AgentCore Runtime dapat mendukung autentikasi masuk berbasis IAM SiGv4 atau JWT Bearer Token, tetapi tidak keduanya secara bersamaan. Anda selalu dapat membuat versi AgentCore Runtime yang berbeda dan mengonfigurasinya untuk jenis otorisasi masuk yang berbeda. Saat Anda membuat runtime dengan Amazon Bedrock AgentCore, Identitas Beban Kerja dibuat secara otomatis untuk runtime Anda dengan layanan Identity. AgentCore
**Topics**
+ [Batasi pemanggilan masuk IAM (SiGv4) ke gateway Anda](#runtime-restrict-iam-gateway)
+ [Otorisasi masuk JWT dan sampel akses keluar OAuth](#oauth-sample-overview)
+ [Prasyarat](#oauth-prerequisites)
+ [Langkah 1: Buat proyek agen Anda](#prepare-agent)
+ [Langkah 2: Mengatur AWS Kumpulan pengguna Cognito dan tambahkan pengguna](#setup-cognito)
+ [Langkah 3 (Opsional): Depan runtime Anda dengan Gateway AgentCore](#runtime-front-with-gateway)
+ [Langkah 4: Menyebarkan agen Anda](#deploy-agent)
+ [Langkah 5: Gunakan token pembawa untuk memanggil agen Anda](#oauth-invoke-agent)
+ [Tanggapan Kesalahan OAuth](#oauth-error-responses)
+ [Langkah 6: Siapkan agen Anda untuk mengakses alat menggunakan OAuth](#oauth-outbound-access)
+ [Langkah 7: (Opsional) Menyebarkan token JWT ke Runtime AgentCore](#oauth-propagate-jwt-token)
+ [Pemecahan masalah](#troubleshooting)
## Batasi pemanggilan masuk IAM (SiGv4) ke gateway Anda
Anda dapat mengedepankan AgentCore Runtime dengan AgentCore Gateway sehingga gateway menjadi titik masuk tunggal yang diatur ke runtime — memberi Anda otorisasi berbasis kebijakan, Amazon Bedrock Guardrails, pencegat permintaan dan respons, dan observabilitas terpadu, semuanya diterapkan di luar lingkungan agen sendiri. Untuk alasan lengkap dan cara mengaturnya, lihat [Front runtime Anda dengan](runtime-security-best-practices.md#security-bp-front-with-gateway) Gateway. AgentCore
Tetapi ini hanya berguna jika penelepon tidak dapat mencapai runtime secara langsung melewati gateway. Jika runtime Anda menggunakan otorisasi masuk IAM (SigV4) default, Anda dapat membatasi pemanggilan ke gateway sehingga lalu lintas mencapai runtime hanya melalui itu. Untuk mencapai hal ini, lampirkan kebijakan berbasis sumber daya ke runtime yang membatasi pemanggilan ke peran eksekusi gateway Anda. Gateway mengasumsikan peran layanannya untuk menandatangani permintaan ke runtime, jadi peran gateway adalah prinsipal yang memanggil runtime. Izinkan peran itu, dan tambahkan eksplisit `Deny` untuk setiap prinsipal lainnya sehingga tidak ada identitas lain yang dapat memanggil runtime bahkan dengan kebijakan berbasis identitas permisif. [Untuk informasi selengkapnya tentang kebijakan berbasis sumber daya tentang runtime, lihat kebijakan Resource-based untuk Amazon Bedrock. AgentCore](resource-based-policies.md)
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowOnlyGatewayRole",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
},
{
"Sid": "DenyOtherPrincipals",
"Effect": "Deny",
"Principal": { "AWS": "*" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
"Condition": {
"ArnNotEquals": {
"aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
}
}
}
]
}
```
**Tip**
Eksplisit `Deny` selalu mengesampingkan kebijakan apa pun`Allow`, termasuk kebijakan berbasis identitas di akun yang sama. Mengaktifkan `aws:PrincipalArn` memastikan bahwa hanya peran eksekusi gateway Anda yang dapat memanggil runtime, terlepas dari izin lain apa yang ada di akun Anda. `Deny`
**penting**
Membatasi runtime ke peran eksekusi gateway hanya sekuat kontrol siapa yang dapat mengambil peran itu. Prinsipal apa pun yang dapat mengasumsikan peran eksekusi gateway dapat memanggil runtime seolah-olah itu adalah gateway. Kunci peran dengan menambahkan `aws:SourceArn` dan `aws:SourceAccount` mengkondisikan ke **kebijakan kepercayaan peran eksekusi gateway** sehingga hanya gateway Anda yang dapat menerimanya. Panduan [pencegahan deputi yang bingung](runtime-security-best-practices.md#security-bp-confused-deputy) menunjukkan teknik yang sama yang diterapkan pada peran eksekusi runtime; terapkan pola yang sama di sini, tetapi tetapkan kebijakan kepercayaan pada peran dan ruang lingkup eksekusi gateway `aws:SourceArn` ke ARN gateway Anda.
## Otorisasi masuk JWT dan sampel akses keluar OAuth
Panduan ini memandu Anda melalui proses pengaturan runtime agen Anda untuk dipanggil dengan token akses yang sesuai dengan OAuth menggunakan format JWT. Agen sampel akan diotorisasi menggunakan token akses AWS Cognito. Kemudian, Anda juga akan mempelajari bagaimana kode agen dapat mengambil token Google atas nama pengguna untuk memeriksa Google Drive dan mengambil konten.
**Apa yang akan Anda pelajari**
Dalam panduan ini, Anda akan belajar cara:
+ Siapkan kumpulan pengguna Cognito, tambahkan pengguna, dan dapatkan token pembawa untuk pengguna
+ Siapkan runtime agen Anda untuk menggunakan kumpulan pengguna Cognito untuk otorisasi
+ Siapkan kode agen Anda untuk mengambil token OAuth atas nama pengguna untuk memanggil alat
## Prasyarat
Sebelum memulai, pastikan Anda memiliki:
+ AWS Akun dengan izin yang sesuai
+ Pemahaman dasar tentang pemrograman Python
+ Keakraban dengan kontainer Docker (untuk penerapan lanjutan)
+ Siapkan agen dasar dengan runtime dengan sukses
+ AWS CLI terbaru dan diinstal `jq`
+ Pemahaman dasar otorisasi OAuth, terutama token pembawa JWT, klaim, dan berbagai aliran hibah
## Langkah 1: Buat proyek agen Anda
Gunakan `agentcore create` perintah untuk menyiapkan proyek agen kerangka dengan kerangka kerja pilihan Anda:
```
agentcore create
```
Perintah akan meminta Anda untuk:
+ Pilih kerangka kerja (pilih Strands Agents untuk tutorial ini)
+ Berikan nama proyek
+ Konfigurasikan opsi tambahan
Ini menghasilkan:
+ Kode agen dengan kerangka kerja yang Anda pilih
+ `agentcore/agentcore.json`berkas konfigurasi
+ `requirements.txt`dengan dependensi yang diperlukan
**catatan**
Kode agen yang dihasilkan akan berfungsi sebagai dasar untuk menerapkan otentikasi OAuth dalam langkah-langkah berikut.
## Langkah 2: Mengatur AWS Kumpulan pengguna Cognito dan tambahkan pengguna
Untuk menyiapkan kumpulan pengguna Cognito dan membuat pengguna, Anda akan menggunakan skrip shell yang mengotomatiskan proses.
Untuk informasi selengkapnya, lihat [Langkah 2: Impor modul Identitas dan Auth](identity-getting-started-google.md#identity-getting-started-step2).
**Untuk mengatur kumpulan pengguna Cognito dan membuat pengguna**
+ Buat file bernama `setup_cognito.sh` dengan konten berikut:
```
#!/bin/bash
# Create User Pool and capture Pool ID directly
export POOL_ID=$(aws cognito-idp create-user-pool \
--pool-name "MyUserPool" \
--policies '{"PasswordPolicy":{"MinimumLength":8}}' \
--region $REGION | jq -r '.UserPool.Id')
# Create App Client and capture Client ID directly
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
--user-pool-id $POOL_ID \
--client-name "MyClient" \
--no-generate-secret \
--explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
--region $REGION | jq -r '.UserPoolClient.ClientId')
# Create User
aws cognito-idp admin-create-user \
--user-pool-id $POOL_ID \
--username $USERNAME \
--region $REGION \
--message-action SUPPRESS > /dev/null
# Set Permanent Password
aws cognito-idp admin-set-user-password \
--user-pool-id $POOL_ID \
--username $USERNAME \
--password $PASSWORD \
--region $REGION \
--permanent > /dev/null
# Authenticate User and capture Access Token
export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
--client-id "$CLIENT_ID" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME=$USERNAME,PASSWORD=$PASSWORD \
--region $REGION | jq -r '.AuthenticationResult.AccessToken')
# Output the required values
echo "Pool id: $POOL_ID"
echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
echo "Client ID: $CLIENT_ID"
echo "Bearer Token: $BEARER_TOKEN"
```
Buka jendela terminal dan atur variabel lingkungan berikut:
+ {{REGION}}— AWS Wilayah yang ingin Anda gunakan
+ {{USERNAME}}— nama pengguna untuk pengguna baru
+ {{PASSWORD}}— kata sandi untuk pengguna baru
```
export REGION=us-east-1 // set your desired Region
export USERNAME=USER NAME
export PASSWORD=PASSWORD
```
Di jendela terminal, jalankan skrip:
```
source setup_cognito.sh
```
Perhatikan output dari skrip. Anda akan membutuhkan nilai-nilai ini di langkah selanjutnya.
Skrip ini membuat kumpulan pengguna Cognito, klien kumpulan pengguna, menambahkan pengguna, dan menghasilkan token pembawa untuk pengguna. Token berlaku selama 60 menit secara default.
## Langkah 3 (Opsional): Depan runtime Anda dengan Gateway AgentCore
Anda dapat mengedepankan AgentCore Runtime dengan AgentCore Gateway sehingga gateway menjadi titik masuk tunggal yang diatur ke runtime — memberi Anda otorisasi berbasis kebijakan, Amazon Bedrock Guardrails, pencegat permintaan dan respons, dan observabilitas terpadu, semuanya diterapkan di luar lingkungan agen sendiri. Untuk alasan lengkap dan cara mengaturnya, lihat [Front runtime Anda dengan](runtime-security-best-practices.md#security-bp-front-with-gateway) Gateway. AgentCore
Jika Anda ingin mendahului runtime ini, [buat gateway](gateway-create.md) sekarang, sebelum Anda menerapkan runtime di langkah berikutnya. Setelah menerapkan, Anda akan [menambahkan runtime sebagai target gateway](gateway-target-http-runtime.md).
Untuk memastikan penelepon tidak dapat melewati gateway, batasi runtime untuk menerima pemanggilan hanya dari gateway itu. Anda mengonfigurasi ini di langkah berikutnya, sebagai bagian dari otorisasi, menggunakan `allowedWorkloadConfiguration` (lihat [diizinkanWorkloadConfiguration: batasi pemanggilan ke](#deploy-agent-allowed-workload) gateway Anda).
## Langkah 4: Menyebarkan agen Anda
**penting**
Mulai **13 Oktober 2025,** Amazon Bedrock AgentCore menggunakan Service-Linked Peran (SLR) untuk izin identitas beban kerja alih-alih memerlukan konfigurasi kebijakan IAM manual untuk agen baru.
Rincian Service-Linked Peran:
**Nama:** `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity`
**Prinsipal Layanan:** `runtime-identity.bedrock-agentcore.amazonaws.com`
**Tujuan:** Mengelola token akses identitas beban kerja dan kredensi OAuth
Pastikan peran yang Anda gunakan untuk memanggil AgentCore Control API memiliki izin untuk membuat Service-Linked Peran:
```
{
"Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
}
}
}
```
**Manfaat**: Service-Linked Peran secara otomatis memberikan izin yang diperlukan untuk akses identitas beban kerja tanpa memerlukan konfigurasi kebijakan manual.
Untuk informasi mendetail tentang peran terkait layanan, lihat Peran terkait [layanan identitas](service-linked-roles.md#identity-service-linked-role).
Sekarang Anda akan menerapkan agen Anda dengan otorisasi JWT menggunakan kumpulan pengguna Cognito yang Anda buat. Anda perlu membuat agen dengan konfigurasi otorisasi. Tabel berikut mewakili berbagai parameter konfigurasi authorizer dan bagaimana kita menggunakannya untuk memvalidasi token masuk.
| authorizer\_configuration | klaim dalam token yang diterjemahkan | Catatan |
| --- | --- | --- |
| url penemuan → penerbit | iss | Url penemuan harus mengarah ke url penerbit. Ini harus cocok dengan klaim iss dalam token yang diterjemahkan. |
| Diizinkan Klien | client\_id | client\_id dalam token harus cocok dengan salah satu klien yang diizinkan yang ditentukan dalam otorisasi |
| Diizinkan Audience | aud | Salah satu nilai dalam klaim aud dari token harus cocok dengan salah satu audiens yang diizinkan yang ditentukan dalam otorisasi |
| diizinkan WorkloadConfiguration | `internal` | Tidak wajib. Saat peluncuran, digunakan untuk mengizinkan hanya AgentCore Gateway Anda untuk memanggil runtime. Lihat [Batasi pemanggilan ke gateway Anda](#deploy-agent-allowed-workload). |
Jika client\_id dan aud disediakan, otorisasi runtime agen akan memverifikasi keduanya.
### diperbolehkanWorkloadConfiguration: batasi pemanggilan ke gateway Anda
`allowedWorkloadConfiguration`Bidang pada `customJWTAuthorizer` membatasi beban kerja dalam rantai identitas permintaan yang diizinkan untuk memanggil runtime. Setel beban kerja yang diizinkan ke gateway Anda sehingga runtime menerima permintaan hanya jika rantai identitasnya menyertakan gateway itu — inilah cara runtime OAuth (JWT) memberlakukan lalu lintas yang tiba hanya melalui gateway yang Anda atur di Langkah 3.
Anda memberikan beban kerja yang diizinkan menggunakan salah satu bidang berikut. Anda dapat menentukan satu atau keduanya — permintaan diterima jika rantai identitasnya cocok dengan entri di **salah satu** bidang, jadi Anda tidak perlu menyediakan keduanya.
+ **HostingEnvironments** — Daftar lingkungan hosting yang beban kerjanya diizinkan untuk memanggil target. Setiap entri adalah objek dengan`arn`. Saat peluncuran, satu-satunya lingkungan hosting yang didukung adalah AgentCore Gateway, jadi masing-masing `arn` harus berupa ARN AgentCore Gateway.
+ **Workloadidentities** — Daftar nama identitas beban kerja yang diizinkan untuk memanggil target. Nama identitas beban kerja **bukan ARN**. Ini adalah segmen terakhir dari ARN identitas beban kerja gateway, yang dapat Anda temukan `workloadIdentityDetails` di bidang respons. `GetGateway` Misalnya, jika `workloadIdentityDetails.workloadIdentityArn` ya`arn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity`, maka nama identitas beban kerja adalah`my-gateway-workload-identity`.
Contoh berikut membuat runtime agen yang membatasi pemanggilan ke Gateway tertentu AgentCore oleh ARN-nya. Menentukan `hostingEnvironments` sendiri adalah cara paling sederhana untuk mengizinkan gateway:
```
{
"authorizerConfiguration": {
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
"allowedClients": ["your-client-id"],
"allowedWorkloadConfiguration": {
"hostingEnvironments": [
{
"arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
}
]
}
}
}
}
```
Atau, Anda dapat mengidentifikasi gateway dengan nama identitas beban kerjanya, atau menentukan kedua bidang. Ketika keduanya hadir, permintaan diizinkan jika cocok dengan entri di kedua bidang. `allowedWorkloadConfiguration`Cuplikan berikut memungkinkan dua gateway yang berbeda - satu diidentifikasi oleh ARN dan satu dengan nama identitas beban kerjanya:
```
"allowedWorkloadConfiguration": {
"hostingEnvironments": [
{
"arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
}
],
"workloadIdentities": [
"my-gateway-2-workload-identity"
]
}
```
**catatan**
Saat peluncuran, hanya `allowedWorkloadConfiguration` didukung untuk target AgentCore Runtime, dan beban kerja yang diizinkan adalah AgentCore Gateway.
### Membuat dan menerapkan runtime agen
Dengan konfigurasi otorisasi Anda siap, buat dan terapkan runtime agen. Contoh berikut menunjukkan bagaimana melakukan ini dengan AgentCore CLI atau AWS SDK for Python (Boto3). Perhatikan ARN runtime agen dari output — Anda akan memerlukannya untuk memanggil agen di langkah berikutnya.
**Example**
**Untuk mengonfigurasi dan menyebarkan agen Anda**
1. Buat proyek agen Anda dengan AgentCore CLI:
```
agentcore create
```
Saat diminta, pilih kerangka kerja Anda (pilih Strands Agents untuk tutorial ini).
1. Menyebarkan agen Anda:
```
agentcore deploy
```
1. Perhatikan ARN runtime agen dari output. Anda akan membutuhkan ini di langkah berikutnya.
**Tip**
Anda juga dapat menjalankan `agentcore create` perintah tanpa tanda untuk pengalaman interaktif sepenuhnya yang memandu Anda melalui penyiapan proyek.
1.
```
import boto3
# Create the client
client = boto3.client('bedrock-agentcore-control', region_name="us-east-1")
# Call the CreateAgentRuntime operation
response = client.create_agent_runtime(
agentRuntimeName='HelloAgent',
agentRuntimeArtifact={
'containerConfiguration': {
'containerUri': '111122223333.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest'
}
},
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": 'COGNITO_DISCOVERY_URL',
"allowedClients": ['COGNITO_CLIENT_ID']
}
},
networkConfiguration={"networkMode":"PUBLIC"},
roleArn='arn:aws:iam::111122223333:role/AgentRuntimeRole',
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
```
## Langkah 5: Gunakan token pembawa untuk memanggil agen Anda
Sekarang agen Anda dikerahkan dengan otorisasi JWT, Anda dapat memanggilnya menggunakan token pembawa.
**catatan**
Jika Anda mem-fronted runtime Anda dengan gateway di [Langkah 3](#runtime-front-with-gateway), tambahkan runtime yang diterapkan sebagai target gateway sebelum Anda memanggil — lihat [target AgentCore Runtime](gateway-target-http-runtime.md) — lalu panggil melalui titik akhir gateway yang ditampilkan dalam contoh berikut, bukan titik akhir runtime.
**penting**
**Penting bagi pengguna yang sudah ada**: Agen yang dibuat **sebelum 13 Oktober 2025** akan terus menggunakan peran eksekusi agen untuk izin identitas dan **mewajibkan** kebijakan sebelumnya untuk dilampirkan ke peran eksekusi agen.
**Agen baru**: Untuk agen yang dibuat **pada atau setelah 13 Oktober 2025**, kebijakan ini **tidak diperlukan** karena izin ditangani secara otomatis oleh Peran. Service-Linked
```
{
"Sid": "GetAgentAccessToken",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForJWT",
"bedrock-agentcore:GetWorkloadAccessTokenForUserId"
],
# point to the workload identity for the runtime; the workload identity can be found in
# the GetAgentRuntime response and has your agent name in it.
"Resource": [
"arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
]
}
```
**Panggil agen**
Ambil token pembawa untuk pengguna yang Anda buat dengan Amazon Cognito.
```
# use the password and other details used when you created the cognito user
export TOKEN=$(aws cognito-idp initiate-auth \
--client-id "$CLIENT_ID" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME='testuser',PASSWORD='PASSWORD' \
--region us-east-1 | jq -r '.AuthenticationResult.AccessToken')
```
Lanjutkan untuk memanggil agen dengan sisa instruksi berikut.
Panggil agen dengan OAuth.
**Example**
1.
```
// Invoke with OAuth token
export PAYLOAD='{"prompt": "hello what is 1+1?"}'
export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://bedrock-agentcore.us-east-1.amazonaws.com"
# If you fronted the runtime with a gateway (Step 3), the core endpoint URL is now your gateway URL
# export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://${GATEWAY_ID}.gateway.bedrock-agentcore.us-east-1.amazonaws.com/${TARGET_NAME}"
export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT"
# If you fronted the runtime with a gateway (Step 3), the preceding URL works but there is also a simpler alternative:
# export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/invocations"
curl -v -X POST "${INVOKE_URL}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "X-Amzn-Trace-Id: your-trace-id" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: your-session-id" \
-d ${PAYLOAD}
```
1. Karena boto3 tidak mendukung pemanggilan dengan token pembawa, Anda harus menggunakan klien HTTP seperti perpustakaan permintaan di Python.
**Untuk memanggil agen Anda dengan token pembawa**
1. Buat skrip Python bernama `invoke_agent.py` dengan konten berikut:
```
import requests
import urllib.parse
import json
import os
# Configuration Constants
REGION_NAME = "AWS_REGION"
# === Agent Invocation Demo ===
invoke_agent_arn = "YOUR_AGENT_ARN_HERE"
auth_token = os.environ.get('TOKEN')
print(f"Using Agent ARN from environment: {invoke_agent_arn}")
# URL encode the agent ARN
escaped_agent_arn = urllib.parse.quote(invoke_agent_arn, safe='')
# Construct the URL — invoke the runtime directly
url = f"https://bedrock-agentcore.{REGION_NAME}.amazonaws.com/runtimes/{escaped_agent_arn}/invocations?qualifier=DEFAULT"
# If you are fronting the runtime with a gateway (see Step 3), invoke through
# the gateway target instead (replace GATEWAY_ID and my-target):
# url = f"https://GATEWAY_ID.gateway.bedrock-agentcore.{REGION_NAME}.amazonaws.com/my-target/invocations"
# Set up headers
headers = {
"Authorization": f"Bearer {auth_token}",
"X-Amzn-Trace-Id": "your-trace-id",
"Content-Type": "application/json",
"X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": "testsession123"
}
# Enable verbose logging for requests
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)
invoke_response = requests.post(
url,
headers=headers,
data=json.dumps({"prompt": "Hello what is 1+1?"})
)
# Print response in a safe manner
print(f"Status Code: {invoke_response.status_code}")
print(f"Response Headers: {dict(invoke_response.headers)}")
# Handle response based on status code
if invoke_response.status_code == 200:
response_data = invoke_response.json()
print("Response JSON:")
print(json.dumps(response_data, indent=2))
elif invoke_response.status_code >= 400:
print(f"Error Response ({invoke_response.status_code}):")
error_data = invoke_response.json()
print(json.dumps(error_data, indent=2))
else:
print(f"Unexpected status code: {invoke_response.status_code}")
print("Response text:")
print(invoke_response.text[:500])
```
1. Ganti {{AWS\_REGION}} dengan AWS Wilayah yang Anda gunakan. dari Langkah 3.
1. Ganti {{YOUR\_AGENT\_ARN\_HERE}} dengan ARN runtime agen Anda yang sebenarnya dari Langkah 3.
1. Jalankan skrip .
```
python invoke_agent.py
```
## Tanggapan Kesalahan OAuth
OAuth-configured agen mengikuti standar [otentikasi RFC 6749 (OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749)). Ketika otentikasi tidak ada, layanan mengembalikan respons 401 Tidak Sah dengan WWW-Authenticate header (per [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), memungkinkan klien menemukan titik akhir server otorisasi melalui API. GetRuntimeProtectedResourceMetadata
### 401 Tidak Sah - Otentikasi Hilang
Ketika tidak ada token Bearer yang disediakan di header Otorisasi, responsnya adalah:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```
`resource_metadata`URL di WWW-Authenticate header menunjuk ke Protected Resource Metadata (PRM) API. API PRM memungkinkan klien untuk menemukan server otorisasi mana yang melindungi agen ini dan URL titik akhir OAuth mereka.
**catatan**
Anda harus melakukan pra-registrasi klien OAuth Anda di Cognito (melalui Konsol AWS atau CLI) untuk mendapatkan sebelum menggunakan titik akhir yang ditemukan. `client_id` Amazon Cognito tidak mendukung Pendaftaran Klien Dinamis (RFC 7591).
## Langkah 6: Siapkan agen Anda untuk mengakses alat menggunakan OAuth
Di bagian ini, Anda akan mempelajari cara menghubungkan kode agen Anda dengan AgentCore Credential Provider untuk akses aman ke sumber daya eksternal menggunakan otentikasi OAuth2.
Contoh berikut menunjukkan bagaimana agen Anda yang berjalan di Agent Runtime dapat meminta persetujuan OAuth dari pengguna, memungkinkan mereka untuk mengautentikasi dengan akun Google mereka dan memberi wewenang kepada agen untuk mengakses konten Google Drive mereka.
Untuk informasi selengkapnya tentang menyiapkan identitas, lihat [Memulai AgentCore Identitas](identity-getting-started.md).
### Langkah 6.1: Siapkan Penyedia Kredensi
Untuk menyiapkan Google Credential Provider, Anda perlu:
1. Daftarkan aplikasi Anda dengan Google untuk mendapatkan ID klien dan rahasia klien
1. Buat penyedia kredensi OAuth menggunakan CLI. AWS Ganti {{your-client-id}} dan {{your-client-secret}} dengan ID klien Google OAuth2 dan rahasia klien Anda yang sebenarnya:
```
OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
--name "google-provider" \
--credential-provider-vendor "GoogleOauth2" \
--oauth2-provider-config-input '{
"googleOauth2ProviderConfig": {
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}
}' \
--output json)
OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')
echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
```
**catatan**
Dapatkan `callbackUrl` dari [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)respons dan tambahkan URI ke daftar URI pengalihan aplikasi Google Anda. URL panggilan balik akan terlihat seperti: https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/ \*\*\*\*\*\*\*\*\*\*-\*\*\*\*-\*\*\*\*\*\*-\*\*\*\*\*\*\*\*\*\*\*\*\*\*
Pastikan peran pemanggilan Anda memiliki izin yang diperlukan untuk mengakses penyedia kredensi.
### Langkah 6.2: Aktifkan agen untuk membaca konten Google Drive
Buat alat dengan anotasi SDK inti agen seperti yang ditunjukkan pada contoh berikut untuk memulai proses OAuth berkaki tiga secara otomatis. Ketika agen Anda memanggil alat ini, pengguna akan diminta untuk membuka URL otorisasi di browser mereka dan memberikan persetujuan kepada agen untuk mengakses Google Drive mereka.
```
import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key
# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
provider_name="google-provider",
scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
auth_flow="USER_FEDERATION", # 3LO flow
on_auth_url=lambda x: print("Copy and paste this authorization url to your browser: ", x), # prints authorization URL to console
force_authentication=True,
callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def read_from_google_drive(*, access_token: str):
print(access_token) #You can see the access_token
# Make API calls...
main(access_token)
asyncio.run(read_from_google_drive(access_token=""))
```
**catatan**
Untuk contoh implementasi server callback lokal untuk menangani [pengikatan sesi](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), lihat [https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py)
**Apa yang terjadi di balik layar**
Ketika kode ini berjalan, proses berikut terjadi:
1. Agent Runtime mengotorisasi token masuk sesuai dengan otorisasi yang dikonfigurasi.
1. Agen Runtime menukar token ini dengan Token Akses Beban Kerja melalui `bedrock-agentcore:GetWorkloadAccessTokenForJWT` API dan mengirimkannya ke kode agen Anda melalui header payload. `WorkloadAccessToken`
1. Selama pemanggilan alat, agen Anda menggunakan Token Akses Beban Kerja ini untuk memanggil Token Vault API `bedrock-agentcore:GetResourceOauth2Token` dan menghasilkan URL otentikasi 3LO.
1. Agen Anda mengirimkan URL ini ke aplikasi klien seperti yang ditentukan dalam `on_auth_url` metode.
1. Aplikasi klien menyajikan URL ini kepada pengguna, yang memberikan persetujuan kepada agen untuk mengakses Google Drive mereka.
1. AgentCore Layanan identitas menerima dan menyimpan token akses Google dengan aman hingga kedaluwarsa, memungkinkan permintaan berikutnya dari pengguna untuk menggunakan token ini tanpa memerlukan pengguna untuk memberikan persetujuan untuk setiap permintaan.
**catatan**
AgentCore Layanan Identitas menyimpan token akses Google di AgentCore Token Vault menggunakan identitas beban kerja agen dan ID pengguna (dari token JWT masuk, seperti token AWS Cognito) sebagai kunci pengikatan, menghilangkan permintaan persetujuan berulang hingga token Google kedaluwarsa.
## Langkah 7: (Opsional) Menyebarkan token JWT ke Runtime AgentCore
Secara opsional, Anda dapat meneruskan header Otorisasi ke AgentCore Runtime untuk mengekstrak klaim. Hal ini dapat dilakukan dengan menggunakan konfigurasi request header allowlist. Untuk informasi selengkapnya, lihat [RequestHeaderConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_RequestHeaderConfiguration.html).
### Langkah 7.1: Ubah kode agen Anda untuk membaca header
Pada langkah ini Anda membuat perubahan pada kode agen Anda sehingga Anda dapat memecahkan kode dan mengekstrak klaim dari token JWT menggunakan pustaka PyJWT.
**requirements.txt**
Tambahkan dependensi PyJWT ke `requirements.txt` file dalam proyek yang Anda hasilkan.
```
PyJWT
```
**Perbarui kode agen Anda**
Ubah file agen utama dalam proyek yang Anda hasilkan (biasanya `src/main.py` atau serupa, tergantung pada pilihan kerangka kerja Anda) seperti yang ditunjukkan dalam kode berikut. Anda dapat melewati validasi tanda tangan token di sini karena telah divalidasi oleh AgentCore Runtime ketika otorisasi masuk selesai.
```
import jwt
import json
....
@app.entrypoint
def invoke(payload, context):
auth_header = context.request_headers.get('Authorization')
if not auth_header:
return None
# Remove "Bearer " prefix if present
token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
try:
# Skip signature validation as agent runtime has validated the token already.
claims = jwt.decode(token, options={"verify_signature": False})
app.logger.info("Claims: %s", json.dumps(claims))
except jwt.InvalidTokenError as e:
app.logger.exception("Invalid JWT token: %s", e)
.....
```
### Langkah 7.2: Buat agen dengan daftar permintaan header allowlist
Gunakan AgentCore CLI untuk mengonfigurasi agen dengan daftar permintaan header allowlist. Arahkan ke direktori proyek yang Anda buat dan jalankan:
```
agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none
# Now deploy the agent runtime
agentcore deploy
```
**catatan**
AgentCore CLI menciptakan struktur proyek dan file konfigurasi. Sesuaikan konfigurasi agen sesuai `agentcore/agentcore.json` kebutuhan untuk pilihan kerangka kerja Anda.
### Langkah 7.3: Panggil agen Anda
[Panggil](#oauth-invoke-agent) agen Anda menggunakan OAuth dan Anda akan melihat klaim di log agen Anda di Log. CloudWatch
## Pemecahan masalah
### Cara men-debug masalah terkait token
Jika Anda mengalami masalah dengan otentikasi token, Anda dapat memecahkan kode token untuk memeriksa isinya:
```
echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i