Créez votre premier agent authentifié

Ce didacticiel de mise en route vous explique comment créer un agent authentifié complet à partir de zéro à l'aide d'Amazon Bedrock AgentCore Identity et vous aidera à commencer à implémenter des fonctionnalités d'identité dans vos applications d'agent. Vous apprendrez à configurer votre environnement de développement, à créer une infrastructure d'authentification avec Cognito, à déployer votre agent sur AgentCore Runtime et à tester le flux de travail d'authentification complet.

À la fin de ce didacticiel, vous disposerez d'un agent entièrement déployé capable d'authentifier les utilisateurs via des flux OAuth2, d'obtenir des jetons d'accès en toute sécurité et de démontrer le cycle de vie complet de la gestion des identités. Votre agent fonctionnera sur AgentCore Runtime avec les autorisations IAM appropriées, créant ainsi un environnement de laboratoire de test dans lequel vous pourrez démontrer et tester les capacités d'intégration.

Conditions préalables

Avant de commencer, assurez-vous de disposer des éléments suivants :

Ce didacticiel nécessite que vous disposiez d'un serveur d'autorisation OAuth 2.0. Si vous n'en avez pas, l'étape 1 en créera un pour vous à l'aide des groupes d'utilisateurs Amazon Cognito. Si vous disposez d'un serveur d'autorisation OAuth 2.0 avec un identifiant client, un secret client et un utilisateur configuré, vous pouvez passer à l'étape 2. Ce serveur d'autorisation agira en tant que fournisseur d'informations d'identification de ressources, représentant l'autorité qui accorde à l'agent un jeton d'accès OAuth 2.0 sortant.

Installation du SDK et des dépendances

Créez un dossier pour ce guide, créez un environnement virtuel Python et installez le AgentCore SDK et le SDK AWS Python (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

Créez également le requirements.txt fichier avec le contenu suivant. Cela sera utilisé ultérieurement par l'outil AgentCore de déploiement.

bedrock-agentcore
boto3
pyjwt
strands-agents

Étape 1 : créer un groupe d'utilisateurs Cognito (facultatif)

Ce didacticiel nécessite un serveur d'autorisation OAuth 2.0. Si aucun test n'est disponible pour le test, ou si vous souhaitez séparer votre test de votre serveur d'autorisation, ce script utilisera vos AWS informations d'identification pour configurer une instance Amazon Cognito que vous utiliserez comme serveur d'autorisation. Le script créera :

La suppression du groupe d'utilisateurs Cognito AgentCoreIdentityQuickStartPool entraîne également la suppression du client_id et de l'utilisateur associés.

Vous pouvez choisir d'enregistrer ce script sous le nom create_cognito.sh et de l'exécuter depuis votre ligne de commande, ou de le coller dans votre ligne de commande.

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

Étape 2 : créer un fournisseur d'informations d'identification

Les fournisseurs d'identifiants permettent à votre agent d'accéder aux services externes. Créez un fournisseur d'informations d'identification et configurez-le avec un client OAuth 2.0 pour votre serveur d'autorisation.

Si vous utilisez votre propre serveur d'autorisation, définissez les variables ISSUER_URL d'environnement et CLIENT_SECRET utilisez leurs valeurs appropriées à partir de votre serveur d'autorisation. CLIENT_ID Si vous utilisez le script précédent pour créer un serveur d'autorisation pour vous avec Cognito, copiez les instructions EXPORT de la sortie dans votre terminal pour définir les variables d'environnement.

Ce fournisseur d'informations d'identification sera utilisé par le code de votre agent pour obtenir des jetons d'accès afin d'agir au nom de votre utilisateur.

Étape 2.5 : Ajoutez l'URL de rappel à votre serveur d'autorisation OAuth 2.0

Pour empêcher les redirections non autorisées, ajoutez l'URL de rappel récupérée depuis CreateOauth2CredentialProviderou GetOauth2CredentialProvidervers votre serveur d'autorisation OAuth 2.0.

Si vous utilisez le script précédent pour créer un serveur d'autorisation avec Cognito, copiez les instructions EXPORT de la sortie dans votre terminal pour définir les variables d'environnement et mettez à jour le client du groupe d'utilisateurs Cognito avec l'URL de rappel du fournisseur d'informations d'identification 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"

Étape 3 : créer un exemple d'agent qui lance un flux OAuth 2.0

Au cours de cette étape, nous allons créer un agent qui initie un flux d'autorisation OAuth 2.0 pour que les jetons agissent au nom de l'utilisateur. Pour des raisons de simplicité, l'agent n'appellera pas réellement les services externes au nom d'un utilisateur, mais il nous prouvera qu'il a obtenu le consentement pour agir au nom de notre utilisateur test.

Code de l'agent

Créez un fichier nommé agentcoreidentityquickstart.py et enregistrez ce 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()

Étape 4 : Déployer l'agent sur AgentCore Runtime

Nous hébergerons cet agent sur AgentCore Runtime. Nous pouvons le faire facilement avec la AgentCore CLI.

Depuis votre terminal, installez la AgentCore CLI et créez un nouveau projet :

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

Copiez votre script d'agent dans le répertoire des agents du projet, en remplaçant l'agent par défaut :

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

Copiez également votre fichier d'exigences dans le répertoire de l'agent pour vous assurer que toutes les dépendances sont incluses dans le déploiement :

cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/

Déployez ensuite votre projet :

cd IdentityQuickstart
agentcore deploy

La CLI synthétise une pile AWS CDK et déploie votre agent dans Runtime. AgentCore Cela prend environ 2 à 3 minutes.

Mettez à jour la politique IAM de l'agent pour pouvoir accéder au coffre à jetons et au secret du client

La AgentCore CLI crée le rôle d'exécution de l'agent lors du déploiement, mais ce rôle n'inclut pas automatiquement les autorisations d'accès au coffre à jetons. Vous devez joindre une politique supplémentaire pour permettre à l'agent de récupérer les jetons OAuth 2.0 lors de l'exécution.

Ce script extrait votre compte et votre région depuis la AWS CLI, trouve le rôle d'exécution de l'agent dans la CloudFormation pile et attache la politique appropriée. Vous pouvez copier et coller ce script ou l'enregistrer dans un fichier et l'exécuter.

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

Étape 5 : Invoquer l'agent

Maintenant que tout est configuré, vous pouvez appeler l'agent. Pour cette démonstration, nous utiliserons la agentcore invoke commande et nos informations d'identification IAM. Nous devrons transmettre les --session-id arguments --user-id et lors de l'utilisation de l'authentification IAM.

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

L'agent renverra ensuite l'URL de votre agentcore invoke commande. Copiez et collez cette URL dans votre navigateur préféré, puis vous serez redirigé vers la page de connexion de votre serveur d'autorisation. Le --user-id paramètre est l'ID utilisateur que vous présentez à AgentCore Identity. Le --session-id paramètre est l'ID de session, qui doit comporter au moins 33 caractères.

Entrez le nom d'utilisateur et le mot de passe de votre utilisateur sur votre serveur d'autorisation lorsque vous y êtes invité sur votre navigateur, ou utilisez la méthode d'authentification préférée que vous avez configurée. Si vous avez utilisé le script de l'étape 1 pour créer une instance de Cognito, vous pouvez la récupérer dans l'historique de votre terminal.

Votre navigateur doit rediriger vers l'URL de rappel OAuth2 que vous avez configurée, qui gère le flux de liaison de session. Assurez-vous que votre serveur de rappel OAuth2 fournit des réponses claires de réussite et d'erreur pour indiquer le statut d'autorisation.

Débogage

Si vous rencontrez des erreurs ou des comportements inattendus, le résultat de l'agent est enregistré dans CloudWatch les journaux Amazon. Une commande de suivi du journal est fournie après l'exécutionagentcore deploy.

Nettoyage

Une fois que vous avez terminé, exécutez agentcore remove all puis agentcore deploy depuis le répertoire de votre projet pour supprimer les ressources AgentCore d'exécution déployées. Supprimez ensuite le groupe d'utilisateurs Amazon Cognito, détachez et supprimez la politique IAM que vous avez créée, puis supprimez le fournisseur d'informations d'identification.

Bonnes pratiques de sécurité

Lorsque vous travaillez avec des informations d'identité :