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

Bangun agen terautentikasi pertama Anda

Tutorial memulai ini memandu Anda membangun agen terautentikasi lengkap dari bawah ke atas menggunakan Amazon Bedrock AgentCore Identity dan akan membantu Anda memulai dengan menerapkan fitur identitas dalam aplikasi agen Anda. Anda akan mempelajari cara mengatur lingkungan pengembangan Anda, membuat infrastruktur otentikasi dengan Cognito, menyebarkan agen Anda ke AgentCore Runtime, dan menguji alur kerja otentikasi penuh.

Pada akhir tutorial ini, Anda akan memiliki agen yang sepenuhnya digunakan yang dapat mengotentikasi pengguna melalui aliran OAuth2, mendapatkan token akses dengan aman, dan menunjukkan siklus hidup manajemen identitas lengkap. Agen Anda akan berjalan di AgentCore Runtime dengan izin IAM yang tepat, menciptakan lingkungan lab uji tempat Anda dapat mendemonstrasikan dan menguji kemampuan integrasi.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

Tutorial ini mengharuskan Anda memiliki server otorisasi OAuth 2.0. Jika Anda tidak memilikinya, Langkah 1 akan membuatnya untuk Anda menggunakan kumpulan pengguna Amazon Cognito. Jika Anda memiliki server otorisasi OAuth 2.0 dengan id klien, rahasia klien, dan pengguna yang dikonfigurasi, Anda dapat melanjutkan ke langkah 2. Server otorisasi ini akan bertindak sebagai penyedia kredensia sumber daya, mewakili otoritas yang memberikan token akses OAuth 2.0 keluar kepada agen.

Instal SDK dan dependensi

Buat folder untuk panduan ini, buat lingkungan virtual Python, dan instal AgentCore SDK dan AWS Python SDK (boto3).

mkdir agentcore-identity-quickstart
cd agentcore-identity-quickstart
python3 -m venv .venv
source .venv/bin/activate
pip install bedrock-agentcore boto3 strands-agents pyjwt

Langkah 1: Buat kumpulan pengguna Cognito (Opsional)

Tutorial ini membutuhkan server otorisasi OAuth 2.0. Jika Anda tidak memiliki satu yang tersedia untuk pengujian, atau jika Anda ingin menjaga pengujian terpisah dari server otorisasi Anda, skrip ini akan menggunakan AWS kredenSIAL Anda untuk menyiapkan instance Amazon Cognito untuk Anda gunakan sebagai server otorisasi. Skrip akan membuat:

Menghapus kumpulan pengguna Cognito AgentCoreIdentityQuickStartPool akan menghapus client_id dan pengguna terkait juga.

Anda dapat memilih untuk menyimpan skrip ini sebagai create_cognito.sh dan menjalankannya dari baris perintah Anda, atau menempelkan skrip ke baris perintah Anda.

#!/bin/bash

REGION=$(aws configure get region)

# Create user pool
USER_POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name AgentCoreIdentityQuickStartPool \
  --query 'UserPool.Id' \
  --no-cli-pager \
  --output text)

# Create user pool domain
DOMAIN_NAME="agentcore-quickstart-$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 5)"
aws cognito-idp create-user-pool-domain \
  --domain $DOMAIN_NAME \
  --no-cli-pager \
  --user-pool-id $USER_POOL_ID > /dev/null

# Create user pool client with secret and hosted UI settings
CLIENT_RESPONSE=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name AgentCoreQuickStart \
  --generate-secret \
  --allowed-o-auth-flows "code" \
  --allowed-o-auth-scopes "openid" "profile" "email" \
  --allowed-o-auth-flows-user-pool-client \
  --supported-identity-providers "COGNITO" \
  --query 'UserPoolClient.{ClientId:ClientId,ClientSecret:ClientSecret}' \
  --output json)

CLIENT_ID=$(echo $CLIENT_RESPONSE | jq -r '.ClientId')
CLIENT_SECRET=$(echo $CLIENT_RESPONSE | jq -r '.ClientSecret')

# Generate random username and password
USERNAME="AgentCoreTestUser$(printf "%04d" $((RANDOM % 10000)))"
PASSWORD="$(LC_ALL=C tr -dc 'A-Za-z0-9!@#$%^&*()_+-=[]{}|;:,.<>?' < /dev/urandom | head -c 16)$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 1)"

# Create user with permanent password
aws cognito-idp admin-create-user \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --output text > /dev/null

aws cognito-idp admin-set-user-password \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --password $PASSWORD \
  --output text > /dev/null \
  --permanent

# Get region

ISSUER_URL="https://cognito-idp.$REGION.amazonaws.com/$USER_POOL_ID/.well-known/openid-configuration"
HOSTED_UI_URL="https://$DOMAIN_NAME.auth.$REGION.amazoncognito.com"

# Output results
echo "User Pool ID: $USER_POOL_ID"
echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"
echo "Issuer URL: $ISSUER_URL"
echo "Hosted UI URL: $HOSTED_UI_URL"
echo "Test User: $USERNAME"
echo "Test Password: $PASSWORD"

echo ""
echo "# Copy and paste these exports to set environment variables for later use:"
echo "export USER_POOL_ID='$USER_POOL_ID'"
echo "export CLIENT_ID='$CLIENT_ID'"
echo "export CLIENT_SECRET='$CLIENT_SECRET'"
echo "export ISSUER_URL='$ISSUER_URL'"
echo "export HOSTED_UI_URL='$HOSTED_UI_URL'"
echo "export COGNITO_USERNAME='$USERNAME'"
echo "export COGNITO_PASSWORD='$PASSWORD'"

Langkah 2: Buat penyedia kredensia

Penyedia kredensi adalah cara agen Anda mengakses layanan eksternal. Buat penyedia kredensi dan konfigurasikan dengan klien OAuth 2.0 untuk server otorisasi Anda.

Jika Anda menggunakan server otorisasi Anda sendiri, atur variabel lingkunganISSUER_URL,CLIENT_ID, dan CLIENT_SECRET dengan nilai yang sesuai dari server otorisasi Anda. Jika Anda menggunakan skrip sebelumnya untuk membuat server otorisasi untuk Anda dengan Cognito, salin pernyataan EXPORT dari output ke terminal Anda untuk mengatur variabel lingkungan.

Penyedia kredensi ini akan digunakan oleh kode agen Anda untuk mendapatkan token akses untuk bertindak atas nama pengguna Anda.

Langkah 2.5: Tambahkan URL panggilan balik ke server otorisasi OAuth 2.0 Anda

Untuk mencegah pengalihan yang tidak sah, tambahkan URL panggilan balik yang diambil dari CreateOauth2CredentialProvider atau GetOauth2CredentialProvider ke server otorisasi OAuth 2.0 Anda.

Jika Anda menggunakan skrip sebelumnya untuk membuat server otorisasi dengan Cognito, salin pernyataan EXPORT dari output ke terminal Anda untuk menyetel variabel lingkungan dan perbarui klien kumpulan pengguna Cognito dengan URL panggilan balik penyedia kredensia OAuth2.

#!/bin/bash
aws cognito-idp update-user-pool-client \
    --user-pool-id $USER_POOL_ID \
    --client-id $CLIENT_ID \
    --client-name AgentCoreQuickStart \
    --allowed-o-auth-flows "code" \
    --allowed-o-auth-scopes "openid" "profile" "email" \
    --allowed-o-auth-flows-user-pool-client \
    --supported-identity-providers "COGNITO" \
    --callback-urls "$OAUTH2_CALLBACK_URL"

Langkah 3: Buat agen sampel yang memulai aliran OAuth 2.0

Pada langkah ini, kita akan membuat agen yang memulai aliran otorisasi OAuth 2.0 untuk mendapatkan token untuk bertindak atas nama pengguna. Untuk kesederhanaan, agen tidak akan melakukan panggilan aktual ke layanan eksternal atas nama pengguna, tetapi akan membuktikan kepada kami bahwa ia telah memperoleh persetujuan untuk bertindak atas nama pengguna uji kami.

Kode agen

Buat file bernamaagentcoreidentityquickstart.py, dan simpan kode ini.

"""
AgentCore Identity Outbound Token Agent

This agent demonstrates the USER_FEDERATION OAuth 2.0 flow.

It handles the OAuth 2.0 user consent flow and inspects the resulting OAuth 2.0 access token.
"""

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from bedrock_agentcore.identity import requires_access_token
import asyncio
import jwt
import logging

app = BedrockAgentCoreApp()

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def decode_jwt(token):
    try:
        decoded = jwt.decode(token, options={"verify_signature": False})
        return decoded
    except Exception as e:
        return {"error": f"Error decoding JWT: {str(e)}"}

class StreamingQueue:
    def __init__(self):
        self.finished = False
        self.queue = asyncio.Queue()

    async def put(self, item):
        await self.queue.put(item)

    async def finish(self):
        self.finished = True
        await self.queue.put(None)

    async def stream(self):
        while True:
            item = await self.queue.get()
            if item is None and self.finished:
                break
            yield item

queue = StreamingQueue()

async def handle_auth_url(url):
    await queue.put(f"Authorization URL, please copy to your preferred browser: {url}")

@requires_access_token(
    provider_name="AgentCoreIdentityQuickStartProvider",
    scopes=["openid"],
    auth_flow="USER_FEDERATION",
    on_auth_url=handle_auth_url, # streams authorization URL to client
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding',
)
async def introspect_with_decorator(*, access_token: str):
    """Introspect token using decorator"""
    logger.info("Inside introspect_with_decorator - decorator succeeded")
    await queue.put({
        "message": "Successfully received an access token to act on behalf of your user!",
        "token_claims": decode_jwt(access_token),
        "token_length": len(access_token),
        "token_preview": f"{access_token[:50]}...{access_token[-10:]}"
    })
    await queue.finish()

@app.entrypoint
async def agent_invocation(payload, context):
    """Handler that uses only the decorator approach"""
    logger.info("Agent invocation started")

    # Start the agent task and immediately begin streaming
    task = asyncio.create_task(introspect_with_decorator())

    # Stream items as they come in
    async for item in queue.stream():
        yield item

    # Wait for task completion
    await task

if __name__ == "__main__":
    app.run()

Langkah 4: Menyebarkan agen ke AgentCore Runtime

Kami akan meng-host agen ini di AgentCore Runtime. Kita dapat melakukan ini dengan mudah dengan AgentCore CLI.

Dari terminal Anda, instal AgentCore CLI dan buat proyek agen Python Strands. Opsi eksplisit membuat agen berbasis kode alih-alih harness:

npm install -g @aws/agentcore
agentcore create --name IdentityQuickstart --language Python --framework Strands \
  --model-provider Bedrock --memory none

Salin skrip agen Anda ke direktori agen proyek, menggantikan agen default:

cp agentcoreidentityquickstart.py IdentityQuickstart/app/IdentityQuickstart/main.py

Tambahkan dependensi JWT ke proyek yang dihasilkan:

cd IdentityQuickstart/app/IdentityQuickstart
uv add pyjwt
cd ../..

Kemudian terapkan proyek Anda:

agentcore deploy

CLI mensintesis tumpukan AWS CDK dan menyebarkan agen Anda ke Runtime. AgentCore Ini memakan waktu sekitar 2-3 menit.

Perbarui kebijakan IAM agen agar dapat mengakses brankas token, dan rahasia klien

AgentCore CLI membuat peran eksekusi agen selama penerapan, tetapi peran tersebut tidak secara otomatis menyertakan izin untuk akses vault token. Anda perlu melampirkan kebijakan tambahan untuk memungkinkan agen mengambil token OAuth 2.0 saat runtime.

Skrip ini mengambil akun dan wilayah Anda dari AWS CLI, menemukan peran eksekusi agen dari CloudFormation tumpukan, dan melampirkan kebijakan yang sesuai. Anda dapat menyalin dan menempelkan skrip ini, atau menyimpannya ke file dan menjalankannya.

#!/bin/bash

# Get account and region from AWS CLI
AWS_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region)

# Get execution role from CloudFormation stack outputs
EXECUTION_ROLE=$(aws cloudformation describe-stack-resources \
  --stack-name AgentCore-IdentityQuickstart-prod \
  --query "StackResources[?ResourceType=='AWS::IAM::Role'].PhysicalResourceId" \
  --output text | head -1)

echo "Parsed values:"
echo "Execution Role: $EXECUTION_ROLE"
echo "Account: $AWS_ACCOUNT"
echo "Region: $REGION"

# Create the policy document with proper variable substitution
cat > agentcore-identity-policy.json << EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessTokenVault",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetResourceOauth2Token",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": ["arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default/workload-identity/*",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default/oauth2credentialprovider/AgentCoreIdentityQuickStartProvider",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default",
        "arn:aws:secretsmanager:$REGION:$AWS_ACCOUNT:secret:bedrock-agentcore-identity!default/oauth2/AgentCoreIdentityQuickStartProvider*"
      ]
    }
  ]
}
EOF

# Create the policy
POLICY_ARN=$(aws iam create-policy \
    --policy-name AgentCoreIdentityQuickStartPolicy$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 4) \
    --policy-document file://agentcore-identity-policy.json \
    --query 'Policy.Arn' \
    --output text)

# Extract role name from ARN and attach policy
ROLE_NAME=$(echo $EXECUTION_ROLE | awk -F'/' '{print $NF}')
aws iam attach-role-policy \
    --role-name $ROLE_NAME \
    --policy-arn $POLICY_ARN

echo "Policy created and attached: $POLICY_ARN"

# Cleanup
rm agentcore-identity-policy.json

Langkah 5: Panggil agen

Sekarang semua ini sudah diatur, Anda dapat memanggil agen. Untuk demo ini, kami akan menggunakan agentcore invoke perintah dan kredenSIAL IAM kami. Kita perlu meneruskan --session-id argumen --user-id dan saat menggunakan otentikasi IAM.

agentcore invoke "TestPayload" --runtime IdentityQuickstart --user-id "SampleUserID" --session-id "ALongThirtyThreeCharacterMinimumSessionIdYouCanChangeThisAsYouNeed"

Agen kemudian akan mengembalikan URL ke agentcore invoke perintah Anda. Salin dan tempel URL itu ke browser pilihan Anda, dan Anda kemudian akan diarahkan ke halaman login server otorisasi Anda. --user-idParameter adalah ID pengguna yang Anda sajikan ke AgentCore Identity. --session-idParameternya adalah ID sesi, yang harus setidaknya 33 karakter.

Masukkan nama pengguna dan kata sandi untuk pengguna Anda di server otorisasi Anda saat diminta di browser Anda, atau gunakan metode otentikasi pilihan yang telah Anda konfigurasikan. Jika Anda menggunakan skrip dari Langkah 1 untuk membuat instance Cognito, Anda dapat mengambilnya dari riwayat terminal Anda.

Browser Anda harus mengalihkan ke URL panggilan balik OAuth2 yang dikonfigurasi, yang menangani alur pengikatan sesi. Pastikan server panggilan balik OAuth2 Anda memberikan respons keberhasilan dan kesalahan yang jelas untuk menunjukkan status otorisasi.

Debugging

Jika Anda mengalami kesalahan atau perilaku tak terduga, output agen ditangkap di CloudWatch log Amazon. Perintah log tailing disediakan setelah Anda menjalankanagentcore deploy.

Bersihkan

Setelah selesai, jalankan agentcore remove all dan kemudian agentcore deploy dari direktori proyek Anda untuk meruntuhkan sumber daya AgentCore Runtime yang digunakan. Kemudian hapus kumpulan pengguna Amazon Cognito, lepaskan dan hapus kebijakan IAM yang Anda buat, dan hapus penyedia kredensia.

Praktik terbaik keamanan

Saat bekerja dengan informasi identitas: