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 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, lihathttps://github.com/awslabs/amazon-bedrock-agentcore-samples/.

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

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

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

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

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:

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

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:

Ini menghasilkan:

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.

Untuk mengatur kumpulan pengguna Cognito dan membuat pengguna

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

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

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 gateway Anda).

Langkah 4: Menyebarkan agen Anda

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

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.

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

diperbolehkanWorkloadConfiguration: batasi pemanggilan ke gateway Anda

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

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. allowedWorkloadConfigurationCuplikan 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"
    ]
}

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.

Langkah 5: Gunakan token pembawa untuk memanggil agen Anda

Sekarang agen Anda dikerahkan dengan otorisasi JWT, Anda dapat memanggilnya menggunakan token pembawa.

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

Tanggapan Kesalahan OAuth

OAuth-configured agen mengikuti standar otentikasi RFC 6749 (OAuth 2.0). Ketika otentikasi tidak ada, 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 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_metadataURL 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.

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.

Langkah 6.1: Siapkan Penyedia Kredensi

Untuk menyiapkan Google Credential Provider, Anda perlu:

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=""))

Apa yang terjadi di balik layar

Ketika kode ini berjalan, proses berikut terjadi:

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.

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

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: