Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Créez votre premier agent authentifié

Ce didacticiel de démarrage 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 les 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 s'exécutera 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 fonctionnalité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 consiste à en créer 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

Étape 1 : Création d'un groupe d'utilisateurs Cognito (facultatif)

Ce didacticiel nécessite un serveur d'autorisation OAuth 2.0. Si aucun d'entre eux n'est disponible pour les tests, 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 pourrez utiliser comme serveur d'autorisation. Le script va créer :

La suppression du groupe d'utilisateurs Cognito AgentCoreIdentityQuickStartPool supprimera également le client_id et l'utilisateur associés.

Vous pouvez choisir d'enregistrer ce script sous le nom create_cognito.sh et de l'exécuter à partir de 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éation d'un fournisseur d'informations d'identification

Les fournisseurs d'informations d'identification permettent à votre agent d'accéder à des 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_ID CLIENT_SECRET indiquez les valeurs appropriées à partir de votre serveur d'autorisation. 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 CreateOauth2CredentialProvider ou GetOauth2CredentialProvider vers 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 pool 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éation d'un exemple d'agent qui lance un flux OAuth 2.0

Au cours de cette étape, nous allons créer un agent qui lance un flux d'autorisation OAuth 2.0 pour que les jetons agissent au nom de l'utilisateur. Par souci de simplicité, l'agent n'appellera pas réellement des services externes pour le compte 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éploiement de 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 projet d'agent Python Strands. Les options explicites créent un agent basé sur du code au lieu d'un harnais :

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

Copiez le script de votre 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

Ajoutez la dépendance JWT au projet généré :

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

Déployez ensuite votre projet :

agentcore deploy

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

Mettez à jour la politique IAM de l'agent pour pouvoir accéder au jeton, au coffre-fort 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 de 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 à partir de l' AWS interface de ligne de commande, trouve le rôle d'exécution de l'agent dans la CloudFormation pile et associe 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 que vous avez configurée. Si vous avez utilisé le script de l'étape 1 pour créer une instance Cognito, vous pouvez la récupérer dans l'historique de votre terminal.

Votre navigateur doit être redirigé 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 en cas de réussite et d'erreur pour indiquer l'état de l'autorisation.

Débogage

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

Nettoyage

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

Bonnes pratiques de sécurité

Lorsque vous travaillez avec des informations d'identité :