Batasi panggilan masuk IAM (SIGv4) ke gateway Anda Otorisasi masuk JWT dan sampel akses keluar OAuth Prasyarat Langkah 1: Buat proyek agen Anda Langkah 2: Siapkan AWS Kumpulan pengguna Cognito dan tambahkan pengguna Langkah 3 (Opsional): Lanjutkan runtime Anda dengan AgentCore Gateway Langkah 4: Menyebarkan agen Anda Langkah 5: Gunakan token pembawa untuk memanggil agen Anda Tanggapan Kesalahan OAuth Langkah 6: Siapkan agen Anda untuk mengakses alat menggunakan OAuth Langkah 7: (Opsional) Menyebarkan token JWT ke Runtime AgentCore Pemecahan masalah

Otentikasi dan otorisasi dengan Auth Inbound dan Auth Outbound

Bagian ini menunjukkan kepada Anda cara menerapkan otentikasi dan otorisasi untuk runtime agen Anda menggunakan token pembawa OAuth dan JWT dengan Identity. AgentCore Anda akan mempelajari cara mengatur kumpulan pengguna Cognito, mengonfigurasi runtime agen Anda untuk otentikasi JWT (Inbound Auth), dan menerapkan OAuth-based akses ke sumber daya pihak ketiga (Auth keluar).

Untuk contoh lengkap, lihathttps://github.com/awslabs/amazon-bedrock-agentcore-samples/.

Untuk informasi tentang menggunakan OAuth dengan server MCP, lihat Menye barkan server MCP di Runtime. AgentCore

Amazon Bedrock AgentCore runtime menyediakan dua mekanisme otentikasi untuk agen yang dihosting:

Otentikasi IAM SIGv4

Mekanisme otentikasi dan otorisasi default yang bekerja secara otomatis tanpa konfigurasi tambahan, mirip dengan AWS API lainnya.

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 X-Amzn-Bedrock-AgentCore-Runtime-User-Id header dalam permintaan Anda. Header ini menggunakan GetWorkloadAccessTokenForUserId jalur secara internal.

catatan

Memanggil InvokeAgentRuntime dengan X-Amzn-Bedrock-AgentCore-Runtime-User-Id header akan memerlukan tindakan IAM baru:bedrock-agentcore:InvokeAgentRuntimeForUser, selain tindakan yang adabedrock-agentcore:InvokeAgentRuntime.

Kapan menggunakan header ini versus otentikasi Token Pembawa JWT

Header ini dirancang untuk kasus penggunaan berikut:

Pelanggan perusahaan dengan pengidentifikasi pengguna yang dikelola pelanggan — Organisasi yang mempertahankan string identitas pengguna mereka sendiri dan perlu meneruskannya ke AgentCore Identitas untuk pengikatan kredensia.
Skenario pengembangan dan memulai cepat — Pembangun yang belum memiliki token IdP yang tersedia dan membutuhkan jalur cepat untuk menguji alur kredensia yang dicakup pengguna.

Untuk penerapan produksi di mana Anda memiliki penyedia identitas yang dikonfigurasi, gunakan otentikasi Token Pembawa JWT sebagai gantinya. Jalur JWT (GetWorkloadAccessTokenForJWT) memvalidasi penerbit token, tanda tangan, dan kedaluwarsa, memberikan bukti kriptografi identitas pengguna. Jal X-Amzn-Bedrock-AgentCore-Runtime-User-Id ur header tidak memverifikasi userID terhadap identitas pengguna akhir yang diautentikasi — jalur 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 Prakti k terbaik keamanan untuk AgentCore 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 prinsipal tepercaya yang harus memiliki izin. bedrock-agentcore:InvokeAgentRuntimeForUser Cakup izin ini ke sumber daya runtime tertentu menggunakan kondisi sumber daya IAM. Jangan memberikannya secara luas melalui kebijakan terkelola atau pernyataan sumber daya wildcard.
Turunkan id pengguna dari prinsipal yang diautentikasi — Nilai id pengguna harus diturunkan dari konteks prinsipal yang diautentikasi (misalnya, identitas pemanggil IAM atau klaim token pengguna) daripada menerima nilai yang disediakan klien secara arbitrer. Ini mencegah pengguna yang diautentikasi menyamar sebagai pengguna lain dengan menentukan pengguna lain secara manual. user-id
Menerapkan pen catatan audit — Catat hubungan antara prinsipal IAM yang diautentikasi (dari konteks SIGv4) dan user-id nilai yang diteruskan. Gunakan AWS CloudTrail untuk memantau InvokeAgentRuntime panggilan yang menyertakan runtimeUserId parameter.

Tolak header dalam konteks yang tidak tepercaya — Untuk runtime di mana delegasi id pengguna 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 otorizer 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 audiens yang diizinkan yang akan divalidasi terhadap klaim aud di token JWT
Klien yang diizinkan - Daftar pengidentifikasi klien yang diizinkan yang akan divalidasi terhadap klaim client_id di token JWT
Cakupan yang diizinkan - Daftar cakupan yang diizinkan yang akan divalidasi terhadap klaim ruang lingkup di token JWT. Bid allowedScopes ang otorisasi akan dikonfigurasi sebagai daftar string.
Klaim khusus yang diperlukan - Daftar klaim yang diperlukan yang akan divalidasi terhadap nama klaim dan nilai yang terkandung dalam token JWT yang masuk. Untuk detail tentang mengonfigurasi otorizer, lihat Meng onfigurasi otorisasi JWT masuk

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 AgentCore Identity.

Topik

Batasi panggilan masuk IAM (SIGv4) ke gateway Anda
Otorisasi masuk JWT dan sampel akses keluar OAuth
Prasyarat
Langkah 1: Buat proyek agen Anda
Langkah 2: Siapkan AWS Kumpulan pengguna Cognito dan tambahkan pengguna
Langkah 3 (Opsional): Lanjutkan runtime Anda dengan AgentCore Gateway
Langkah 4: Menyebarkan agen Anda
Langkah 5: Gunakan token pembawa untuk memanggil agen Anda
Tanggapan Kesalahan OAuth
Langkah 6: Siapkan agen Anda untuk mengakses alat menggunakan OAuth
Langkah 7: (Opsional) Menyebarkan token JWT ke Runtime AgentCore
Pemecahan masalah

Batasi panggilan masuk IAM (SIGv4) ke gateway Anda

Anda dapat memajukan AgentCore Runtime Anda 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 pengamatan terpadu, semuanya diterapkan di luar lingkungan agen itu sendiri. Untuk alasan lengkap dan cara mengaturnya, lihat Mengawali runtime Anda dengan AgentCore Gateway.

Tetapi ini hanya berguna jika pemanggil 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 melaluinya. Untuk mencapai hal ini, lampirkan kebijakan berbasis sumber daya ke runtime yang membatasi pemanggilan ke peran eksekusi gateway Anda. Gateway mengambil peran layanannya untuk menandatangani permintaan ke runtime, sehingga peran gateway adalah prinsip 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 Resource-based kebijakan untuk Amazon Bedrock. AgentCore


{
    "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

Sebuah eksplisit Deny selalu mengesampingkan apa punAllow, termasuk kebijakan berbasis identitas di akun yang sama. Mengetik tombol Deny on aws:PrincipalArn memastikan bahwa hanya peran eksekusi gateway Anda yang dapat memanggil runtime, terlepas dari izin lain apa yang ada di akun Anda.

penting

Membatasi runtime ke peran eksekusi gateway hanya sekuat kontrol siapa yang dapat mengambil peran itu. Setiap prinsipal yang dapat mengasumsikan peran eksekusi gateway dapat memanggil runtime seolah-olah itu adalah gateway. Mengunci peran dengan menambahkan aws:SourceArn dan meng aws:SourceAccount kondisikan kebijakan kepercayaan peran eksekusi gateway sehingga hanya gateway Anda yang dapat mengasumsikannya. Panduan pencegahan wakil yang bingung menunjukkan teknik yang sama yang diterapkan pada peran eksekusi runtime; terapkan pola yang sama di sini, tetapi tetapkan kebijakan kepercayaan pada peran dan cakupan eksekusi gateway aws:SourceArn ke ARN gateway Anda.

Otorisasi masuk JWT dan sampel akses keluar OAuth

Panduan ini memandu Anda melalui proses menyiapkan 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 bagaimana:

Siapkan kumpulan pengguna Cognito, tambahkan pengguna, dan dapatkan token pembawa untuk pengguna
Menyiapkan 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 pemrograman Python
Keakraban dengan kontainer Docker (untuk penerapan lanjutan)
Menyiapkan agen dasar dengan runtime berhasil
AWS CLI terbaru dan diinstal jq
Pemahaman dasar tentang otorisasi OAuth, terutama token pembawa JWT, klaim, dan berbagai aliran hibah

Langkah 1: Buat proyek agen Anda

Gunakan agentcore create perintah untuk mengatur proyek kosong. Anda menambahkan JWT-authorized agen setelah membuat sumber daya Cognito di Langkah 2.


agentcore create --project-name OAuthAgentProject --no-agent
cd OAuthAgentProject

Ini menghasilkan:

agentcore/agentcore.jsonberkas konfigurasi
agentcore/aws-targets.jsonfile target penerapan
agentcore/cdk/proyek infrastruktur

catatan

Simpan terminal ini OAuthAgentProject untuk perintah AgentCore CLI yang tersisa.

Langkah 2: Siapkan AWS Kumpulan pengguna Cognito dan tambahkan pengguna

Untuk mengatur 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.

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— Wil AWS ayah 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 ini berlaku selama 60 menit secara default.

Langkah 3 (Opsional): Lanjutkan runtime Anda dengan AgentCore Gateway

Jika Anda ingin memajukan runtime ini, buat gateway sekarang, sebelum Anda menerapkan runtime di langkah berikutnya. Setelah Anda menerapkan, Anda akan menambahkan runtime sebagai target gateway.

Untuk memastikan pemanggil tidak dapat melewati gateway, batasi runtime untuk menerima pemanggilan hanya dari gateway itu. Gunakan allowedWorkloadConfiguration seperti yang dijelaskan dalam diizinkanWorkloadConfiguration: batasi pemanggilan ke gateway Anda. AgentCore CLI tidak mengkonfigurasi bidang ini. Gunakan API AgentCore control-plane.

Langkah 4: Menyebarkan agen Anda

penting

Mulai 13 Oktober 2025, Amazon Bedrock AgentCore menggunakan Peran (SLR) untuk izin identitas beban kerja alih-alih memerlukan konfigurasi kebijakan IAM manual untuk agen baru. Service-Linked

Rincian Service-Linked Peran:

Nama: AWSServiceRoleForBedrockAgentCoreRuntimeIdentity
Kepala Layanan: runtime-identity.bedrock-agentcore.amazonaws.com
Tujuan: Mengel ola token akses identitas beban kerja dan kredenSIAL OAuth

Pastikan peran yang Anda gunakan untuk memanggil API AgentCore Kontrol 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 terperinci tentang peran yang ditautkan layanan, lihat Peran terkait layanan identitas.

Sekarang Anda akan menerapkan agen Anda dengan otorisasi JWT menggunakan kumpulan pengguna Cognito yang Anda buat. Anda perlu membuat agen dengan konfigurasi otorizer. Tabel berikut mewakili berbagai parameter konfigurasi otorizer dan bagaimana kami menggunakannya untuk memvalidasi token yang masuk.

Konfigurasi_otorisasi	klaim dalam token yang didekodekan	Catatan
url penemuan → penerbit	is	Url penemuan harus menunjuk ke url penerbit. Ini harus cocok dengan klaim iss dalam token yang diterjemahkan.
Klien yang Diizinkan	client_id	client_id dalam token harus cocok dengan salah satu klien yang diizinkan yang ditentukan dalam otorizer
DiizinkanAudiens	aud	Salah satu nilai dalam klaim aud dari token harus cocok dengan salah satu audiens yang diizinkan yang ditentukan dalam otorizer
diizinkan WorkloadConfiguration	`internal`	Tidak wajib. Saat peluncuran, digunakan untuk mengizinkan hanya AgentCore Gateway Anda untuk memanggil runtime. Lihat Mem batasi pemanggilan ke gateway Anda.

Jika client_id dan aud disediakan, agen runtime authorizer akan memverifikasi keduanya.

diizinkanWorkloadConfiguration: batasi pemanggilan ke gateway Anda

Bid allowedWorkloadConfiguration ang pada customJWTAuthorizer membatasi beban kerja mana dalam rantai identitas permintaan yang diizinkan untuk memanggil runtime. Atur beban kerja yang diizinkan ke gateway Anda sehingga runtime menerima permintaan hanya ketika rantai identitasnya menyertakan gateway itu — beginilah cara runtime OAuth (JWT) memberlakukan lalu lintas hanya datang melalui gateway yang Anda atur di Langkah 3.

Anda menyediakan 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 memberikan keduanya.

HostingEnviron ments — Daftar lingkungan hosting yang beban kerjanya diizinkan untuk memanggil target. Setiap entri adalah objek denganarn. Saat peluncuran, satu-satunya lingkungan hosting yang didukung adalah AgentCore Gateway, jadi masing-masing arn harus menjadi AgentCore Gateway ARN.
WorkLoadIdentities — Daftar nama identitas beban kerja yang diizinkan untuk memanggil target. Nama identitas beban kerja bukan ARN. Ini adalah segmen terakhir dari identitas beban kerja gateway ARN, yang dapat Anda temukan di workloadIdentityDetails bidang GetGateway respons. Misalnya, jika workloadIdentityDetails.workloadIdentityArn adaarn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity, maka nama identitas beban kerja adalahmy-gateway-workload-identity.

Konfigurasi otorizer berikut membatasi pemanggilan ke AgentCore Gateway tertentu oleh ARN-nya. Men hostingEnvironments entukan 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 tersebut. Ketika keduanya hadir, permintaan diizinkan jika cocok dengan entri di salah satu bidang. Cup allowedWorkloadConfiguration likan berikut memungkinkan dua gateway yang berbeda — satu diidentifikasi oleh ARN-nya 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 otorizer Anda siap, buat dan terapkan runtime agen. Contoh berikut menunjukkan cara melakukan ini dengan AgentCore CLI atau AWS SDK untuk Python (Boto3). Perhatikan ARN runtime agen dari output — Anda akan membutuhkannya untuk memanggil agen di langkah berikutnya.

contoh

AgentCore CLI

Untuk mengonfigurasi dan menyebarkan agen Anda

Tambahkan agen ke proyek yang Anda buat di Langkah 1. Perintah mengonfigurasi URL penemuan Cognito, ID klien, dan daftar izin header Authorization permintaan:


agentcore add agent \
  --name OAuthAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration" \
  --allowed-clients "$CLIENT_ID" \
  --request-header-allowlist Authorization

Menyebarkan agen Anda:
```
agentcore deploy
```
Perhatikan ARN runtime agen dari output. Anda akan membutuhkan ini di langkah berikutnya.

Python


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
    },
)

catatan

Contoh AgentCore CLI mengonfigurasi otorisasi JWT, tetapi tidak mengkonfigurasi. allowedWorkloadConfiguration Jika Anda mengawali runtime dengan gateway, gunakan API AgentCore control-plane untuk menambahkan bidang itu.

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 mengawali runtime Anda dengan gateway di Langkah 3, tambahkan runtime yang digunakan sebagai target gateway sebelum Anda memanggil — lihat Target AgentCore Runtime — lalu panggil melalui titik akhir gateway yang ditunjukkan dalam contoh berikut, bukan titik akhir runtime.

penting

Penting untuk pengguna yang sudah ada: Agen yang dibuat sebelum 13 Oktober 2025 akan terus menggunakan peran eksekusi agen untuk izin identitas dan menghar uskan 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 Service-Linked Peran.


{
    "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-*"
    ]
}

Memanggil 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.

contoh

Use cURL


// 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}

Use Python

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

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])

Ganti AWS_REGION dengan Wil AWS ayah yang Anda gunakan. dari Langkah 3.
Ganti YOUR_AGENT_ARN_HERE dengan ARN runtime agen aktual Anda dari Langkah 3.
Jalankan skrip .
```
python invoke_agent.py
```

Tanggapan Kesalahan OAuth

OAuth-configured agen mengikuti standar otentikasi RFC 6749 (OAuth 2.0). Ketika otentikasi hilang, layanan mengembalikan respons 401 Tidak Sah dengan WWW-Authenticate header (per RFC 7235), memungkinkan klien menemukan titik akhir server otorisasi melalui API. GetRuntimeProtectedResourceMetadata

401 Tidak Sah - Otentikasi Hilang

Ketika tidak ada token Pembawa 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_metadataURL di WWW-Authenticate header menunjuk ke API Metadata Sumber Daya Terlindungi (PRM). API PRM memungkinkan klien menemukan server otorisasi mana yang melindungi agen ini dan URL titik akhir OAuth mereka.

catatan

Anda harus melakukan pra-pendaftaran klien OAuth Anda di Cognito (melalui AWS Konsol atau CLI) untuk mendapatkan client_id sebelum menggunakan titik akhir yang ditemukan. 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 Penyedia AgentCore Kredensi 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 melakukan otentikasi dengan akun Google mereka dan mengotorisasi agen untuk mengakses konten Google Drive mereka.

Untuk informasi selengkapnya tentang menyiapkan identitas, lihat Memulai dengan AgentCore Identitas.

Langkah 6.1: Siapkan Penyedia Kredensia

Untuk menyiapkan Penyedia Kredensi Google, Anda perlu:

Daftarkan aplikasi Anda dengan Google untuk mendapatkan ID klien dan rahasia klien

Buat penyedia kredensia OAuth menggunakan CLI. AWS Ganti your-client-id dan your-client-secret dengan ID klien Google OAuth2 Anda yang sebenarnya dan rahasia klien:


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 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 kredensia.

Langkah 6.2: Aktifkan agen untuk membaca konten Google Drive

Buat alat dengan anotasi SDK inti agen seperti yang ditunjukkan pada contoh berikut untuk secara otomatis memulai proses OAuth tiga kaki. Saat 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, lihat oauth2_callback_server.py di GitHub

Apa yang terjadi di balik layar

Ketika kode ini berjalan, proses berikut terjadi:

Agent Runtime mengotorisasi token masuk sesuai dengan otorizer yang dikonfigurasi.
Agent Runtime menukar token ini dengan Token Akses Beb bedrock-agentcore:GetWorkloadAccessTokenForJWT an Kerja melalui API dan mengirimkannya ke kode agen Anda melalui header WorkloadAccessToken payload.
Selama pemanggilan alat, agen Anda menggunakan Token Akses Beban Kerja ini untuk memanggil Token Vault API bedrock-agentcore:GetResourceOauth2Token dan menghasilkan URL otentikasi 3LO.
Agen Anda mengirimkan URL ini ke aplikasi klien seperti yang ditentukan dalam on_auth_url metode.
Aplikasi klien menyajikan URL ini kepada pengguna, yang memberikan persetujuan kepada agen untuk mengakses Google Drive mereka.
AgentCore Layanan identitas menerima dan menyimpan token akses Google dengan aman hingga kedaluwarsa, memungkinkan permintaan selanjutnya dari pengguna untuk menggunakan token ini tanpa perlu pengguna memberikan persetujuan untuk setiap permintaan.

catatan

AgentCore Identity Service 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. Ini dapat dilakukan dengan menggunakan konfigurasi allowlist header permintaan. Untuk informasi selengkapnya, lihat RequestHeaderConfiguration.

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.

Ketergantungan Python

Tambahkan PyJWT ke agen yang dihasilkan: pyproject.toml


cd app/OAuthAgent
uv add PyJWT
cd ../..

Perbarui kode agen Anda

U app/OAuthAgent/main.py bah seperti yang ditunjukkan dalam kode berikut. Anda dapat melewatkan validasi tanda tangan token di sini karena AgentCore Runtime telah memvalidasi token selama otorisasi masuk.


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: Menerapkan agen yang diperbarui

Per agentcore add agent intah di Langkah 4 sudah mengkonfigurasi header Authorization permintaan allowlist. Terapkan pembaruan kode:


agentcore deploy

Langkah 7.3: Panggil agen Anda

Panggil 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<l; i++) printf "="; print "" }' | base64 -D | jq

Ini akan menampilkan payload token, yang terlihat mirip dengan:


{
    "sub": "subid",
    "iss": "https://cognito-idp.us-east-1.amazonaws.com/userpoolid",
    "client_id": "clientid",
    "origin_jti": "originjti",
    "event_id": "eventid",
    "token_use": "access",
    "scope": "aws.cognito.signin.user.admin",
    "auth_time": 1752275688,
    "exp": 1752279288,
    "iat": 1752275688,
    "jti": "jti",
    "username": "username"
}

Saat memecahkan masalah token, periksa hal berikut:

Url penerbit yang ditunjuk oleh url penemuan di agen otorizer harus cocok dengan klaim penerbit di token. Lakukan hal berikut untuk mengonfirmasi bahwa mereka cocok:
- Pilih url penemuan yang Anda berikan dalam konfigurasi otorizer saat Anda membuat agen, misalnya: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_nnnnnnnnn/.well-known/openid-configuration
  - Periksa url penerbit -"issuer": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_12345566". Ini harus cocok dengan nilai klaim iss di token.
client_idklaim dalam token harus cocok dengan salah satu entri otorizer allowedClients jika disediakan
- Catat id klien yang Anda berikan saat membuat agen
- Konfirmasikan ini cocok dengan klaim client_id di token yang diterjemahkan
audklaim dalam token harus cocok dengan salah satu allowedAudience entri otorisasi, jika disediakan
- Catat daftar audiens yang Anda berikan saat membuat agen
- Konfirmasikan ini cocok dengan aud klaim di token yang didekodekan
Token hanya berlaku selama beberapa menit (kadaluwarsa Amazon Cognito default adalah 60 menit). Ambil token baru sesuai kebutuhan.

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

Lewati header kustom

AgentCore Versi runtime dan titik akhir