Erstellen Sie Ihren ersten authentifizierten Agenten

Dieses Tutorial für die ersten Schritte führt Sie durch die Erstellung eines vollständigen authentifizierten Agenten von Grund auf mit Amazon Bedrock AgentCore Identity und hilft Ihnen bei den ersten Schritten mit der Implementierung von Identitätsfunktionen in Ihren Agentenanwendungen. Sie erfahren, wie Sie Ihre Entwicklungsumgebung einrichten, eine Authentifizierungsinfrastruktur mit Cognito erstellen, Ihren Agenten in AgentCore Runtime bereitstellen und den vollständigen Authentifizierungsworkflow testen.

Am Ende dieses Tutorials verfügen Sie über einen vollständig bereitgestellten Agenten, der Benutzer über OAuth2-Flows authentifizieren, Zugriffstoken sicher abrufen und den gesamten Identitätsmanagement-Lebenszyklus demonstrieren kann. Ihr Agent wird auf AgentCore Runtime mit den entsprechenden IAM-Berechtigungen ausgeführt, wodurch eine Testlab-Umgebung entsteht, in der Sie die Integrationsfunktionen demonstrieren und testen können.

Voraussetzungen

Stellen Sie vor Beginn sicher, dass Sie über Folgendes verfügen:

Für dieses Tutorial benötigen Sie einen OAuth 2.0-Autorisierungsserver. Wenn Sie noch keinen haben, erstellt Schritt 1 einen für Sie mithilfe von Amazon Cognito Cognito-Benutzerpools. Wenn Sie einen OAuth 2.0-Autorisierungsserver mit einer Client-ID, einem geheimen Clientschlüssel und einem konfigurierten Benutzer haben, können Sie mit Schritt 2 fortfahren. Dieser Autorisierungsserver fungiert als Anbieter von Ressourcenanmeldeinformationen und stellt die Autorität dar, die dem Agenten ein ausgehendes OAuth 2.0-Zugriffstoken gewährt.

Installieren Sie das SDK und die Abhängigkeiten

Erstellen Sie einen Ordner für dieses Handbuch, erstellen Sie eine virtuelle Python-Umgebung und installieren Sie das AgentCore SDK und das 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

Erstellen Sie außerdem die requirements.txt Datei mit dem folgenden Inhalt. Dies wird später vom AgentCore Bereitstellungstool verwendet.

bedrock-agentcore
boto3
pyjwt
strands-agents

Schritt 1: Einen Cognito-Benutzerpool erstellen (optional)

Für dieses Tutorial ist ein OAuth 2.0-Autorisierungsserver erforderlich. Wenn Sie keinen zum Testen zur Verfügung haben oder wenn Sie Ihren Test von Ihrem Autorisierungsserver trennen möchten, verwendet dieses Skript Ihre AWS Anmeldeinformationen, um eine Amazon Cognito Cognito-Instanz einzurichten, die Sie als Autorisierungsserver verwenden können. Das Skript erstellt:

Durch das Löschen des Cognito-Benutzerpools AgentCoreIdentityQuickStartPool werden auch die zugehörige client_id und der zugehörige Benutzer gelöscht.

Sie können dieses Skript als create_cognito.sh speichern und von Ihrer Befehlszeile aus ausführen oder das Skript in Ihre Befehlszeile einfügen.

#!/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'"

Schritt 2: Erstellen Sie einen Anbieter für Anmeldeinformationen

Über Anbieter von Anmeldeinformationen greift Ihr Agent auf externe Dienste zu. Erstellen Sie einen Anbieter für Anmeldeinformationen und konfigurieren Sie ihn mit einem OAuth 2.0-Client für Ihren Autorisierungsserver.

Wenn Sie Ihren eigenen Autorisierungsserver verwenden, legen Sie die Umgebungsvariablen ISSUER_URL und CLIENT_SECRET die entsprechenden Werte von Ihrem Autorisierungsserver fest. CLIENT_ID Wenn Sie das vorherige Skript verwenden, um mit Cognito einen Autorisierungsserver für Sie zu erstellen, kopieren Sie die EXPORT-Anweisungen aus der Ausgabe in Ihr Terminal, um die Umgebungsvariablen festzulegen.

Dieser Anmeldeinformationsanbieter wird vom Code Ihres Agenten verwendet, um Zugriffstoken zu erhalten, die im Namen Ihres Benutzers handeln.

Schritt 2.5: Fügen Sie die Callback-URL zu Ihrem OAuth 2.0-Autorisierungsserver hinzu

Um unbefugte Weiterleitungen zu verhindern, fügen Sie die von CreateOauth2CredentialProvideroder zu Ihrem OAuth 2.0-Autorisierungsserver abgerufene Callback-URL GetOauth2CredentialProviderhinzu.

Wenn Sie das vorherige Skript verwenden, um einen Autorisierungsserver mit Cognito zu erstellen, kopieren Sie die EXPORT-Anweisungen aus der Ausgabe in Ihr Terminal, um die Umgebungsvariablen festzulegen, und aktualisieren Sie den Cognito-Benutzerpool-Client mit der Callback-URL des OAuth2-Anmeldeinformationsanbieters.

#!/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"

Schritt 3: Erstellen Sie einen Beispielagenten, der einen OAuth 2.0-Flow initiiert

In diesem Schritt erstellen wir einen Agenten, der einen OAuth 2.0-Autorisierungsablauf initiiert, um Token zu erhalten, die im Namen des Benutzers agieren können. Der Einfachheit halber wird der Agent nicht im Namen eines Benutzers tatsächlich externe Dienste aufrufen, sondern uns nachweisen, dass er die Zustimmung erhalten hat, im Namen unseres Testbenutzers zu handeln.

Agentencode

Erstellen Sie eine Datei mit dem Namen agentcoreidentityquickstart.py und speichern Sie diesen Code.

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

Schritt 4: Stellen Sie den Agenten für Runtime bereit AgentCore

Wir werden diesen Agenten auf AgentCore Runtime hosten. Wir können das ganz einfach mit der AgentCore CLI machen.

Installieren Sie von Ihrem Terminal aus die AgentCore CLI und erstellen Sie ein neues Projekt:

npm install -g @aws/agentcore
agentcore create --name IdentityQuickstart --defaults

Kopieren Sie Ihr Agentenskript in das Agentenverzeichnis des Projekts und ersetzen Sie dabei den Standard-Agenten:

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

Kopieren Sie außerdem Ihre Anforderungsdatei in das Agentenverzeichnis, um sicherzustellen, dass alle Abhängigkeiten in der Bereitstellung enthalten sind:

cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/

Stellen Sie dann Ihr Projekt bereit:

cd IdentityQuickstart
agentcore deploy

Die CLI synthetisiert einen AWS CDK-Stack und stellt Ihren Agenten in Runtime bereit. AgentCore Dies dauert ungefähr 2—3 Minuten.

Aktualisieren Sie die IAM-Richtlinie des Agenten, um auf den Token-Vault und den geheimen Client-Schlüssel zugreifen zu können

Die AgentCore CLI erstellt die Ausführungsrolle des Agenten während der Bereitstellung, aber die Rolle beinhaltet nicht automatisch Berechtigungen für den Token-Vault-Zugriff. Sie müssen eine zusätzliche Richtlinie anhängen, damit der Agent zur Laufzeit OAuth 2.0-Token abrufen kann.

Dieses Skript ruft Ihr Konto und Ihre Region von der AWS CLI ab, sucht die Ausführungsrolle des Agenten aus dem CloudFormation Stack und fügt die entsprechende Richtlinie an. Sie können dieses Skript kopieren und einfügen oder es in einer Datei speichern und ausführen.

#!/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

Schritt 5: Rufen Sie den Agenten auf

Jetzt, da alles eingerichtet ist, können Sie den Agenten aufrufen. Für diese Demo verwenden wir den agentcore invoke Befehl und unsere IAM-Anmeldeinformationen. Wir müssen die --session-id Argumente --user-id und übergeben, wenn wir die IAM-Authentifizierung verwenden.

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

Der Agent gibt dann eine URL an Ihren agentcore invoke Befehl zurück. Kopieren Sie diese URL und fügen Sie sie in Ihren bevorzugten Browser ein. Anschließend werden Sie zur Anmeldeseite Ihres Autorisierungsservers weitergeleitet. Der --user-id Parameter ist die Benutzer-ID, die Sie AgentCore Identity präsentieren. Der --session-id Parameter ist die Sitzungs-ID, die mindestens 33 Zeichen lang sein muss.

Geben Sie den Benutzernamen und das Passwort für Ihren Benutzer auf Ihrem Autorisierungsserver ein, wenn Sie in Ihrem Browser dazu aufgefordert werden, oder verwenden Sie Ihre bevorzugte Authentifizierungsmethode, die Sie konfiguriert haben. Wenn Sie das Skript aus Schritt 1 verwendet haben, um eine Cognito-Instanz zu erstellen, können Sie dies aus Ihrem Terminalverlauf abrufen.

Ihr Browser sollte zu Ihrer konfigurierten OAuth2-Callback-URL weiterleiten, die den Sitzungsbindungsfluss verarbeitet. Stellen Sie sicher, dass Ihr OAuth2-Callback-Server eindeutige Erfolgs- und Fehlerantworten liefert, um den Autorisierungsstatus anzugeben.

Debuggen

Sollten Sie auf Fehler oder unerwartetes Verhalten stoßen, wird die Ausgabe des Agenten in CloudWatch Amazon-Protokollen erfasst. Nach der Ausführung agentcore deploy wird ein Befehl zur Protokollierung bereitgestellt.

Bereinigen

Wenn Sie fertig sind, führen Sie den agentcore remove all Befehl und dann agentcore deploy von Ihrem Projektverzeichnis aus, um die bereitgestellten AgentCore Runtime-Ressourcen zu löschen. Löschen Sie dann den Amazon Cognito Cognito-Benutzerpool, trennen und löschen Sie die von Ihnen erstellte IAM-Richtlinie und löschen Sie den Anmeldeinformationsanbieter.

Bewährte Methoden für die Gewährleistung der Sicherheit

Bei der Arbeit mit Identitätsinformationen: