# Créez votre premier agent authentifié
<a name="identity-getting-started-cognito"></a>

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.

**Topics**
+ [Conditions préalables](#identity-quick-start-prerequisites)
+ [Étape 1 : créer un groupe d'utilisateurs Cognito (facultatif)](#identity-quick-start-cognito)
+ [Étape 2 : créer un fournisseur d'informations d'identification](#identity-quick-start-credential-provider)
+ [Étape 2.5 : Ajoutez l'URL de rappel à votre serveur d'autorisation OAuth 2.0](#identity-update-credential-provider)
+ [Étape 3 : créer un exemple d'agent qui lance un flux OAuth 2.0](#identity-quick-start-agent)
+ [Étape 4 : Déployer l'agent sur AgentCore Runtime](#identity-quick-start-deploy)
+ [Étape 5 : Invoquer l'agent](#identity-quick-start-invoke)
+ [Nettoyage](#identity-quick-start-cleanup)
+ [Bonnes pratiques de sécurité](#identity-quick-start-security)

## Conditions préalables
<a name="identity-quick-start-prerequisites"></a>

Avant de commencer, assurez-vous de disposer des éléments suivants :
+ Un AWS compte avec les autorisations appropriées
+ Python 3.10\+ installé
+ La dernière AWS CLI et `jq` installée
+ Node.js Plus de 18 personnes installées (pour la AgentCore CLI)
+  AWS informations d'identification et région configurées (`aws configure`)

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
<a name="identity-quick-start-install"></a>

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)
<a name="identity-quick-start-cognito"></a>

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 :
+ Un pool d'utilisateurs de Cognito
+ Un client OAuth 2.0 et un secret client pour ce groupe d'utilisateurs
+ Un utilisateur et un mot de passe de test dans ce groupe d'utilisateurs de Cognito

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
<a name="identity-quick-start-credential-provider"></a>

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.

**Example**  

1. Si vous avez un projet AgentCore CLI, vous pouvez ajouter le fournisseur d'informations d'identification à l'aide de la CLI. La CLI créera le fournisseur lors du déploiement.

   ```
   agentcore add credential \
     --name AgentCoreIdentityQuickStartProvider \
     --type oauth \
     --discovery-url "$ISSUER_URL" \
     --client-id "$CLIENT_ID" \
     --client-secret "$CLIENT_SECRET"
   ```

   Le fournisseur d'informations d'identification sera créé lors de l'exécution de `agentcore deploy` l'étape 4. Notez l'URL de rappel figurant dans le résultat du déploiement.

1. 

   ```
   #!/bin/bash
   # please note the expected ISSUER_URL format for Bedrock AgentCore is the full url, including .well-known/openid-configuration
   OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
     --name "AgentCoreIdentityQuickStartProvider" \
     --credential-provider-vendor "CustomOauth2" \
     --oauth2-provider-config-input '{
       "customOauth2ProviderConfig": {
         "oauthDiscovery": {
           "discoveryUrl": "'$ISSUER_URL'"
         },
         "clientId": "'$CLIENT_ID'",
         "clientSecret": "'$CLIENT_SECRET'"
       }
     }' \
     --output json)
   
   OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')
   
   echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
   ```

## Étape 2.5 : Ajoutez l'URL de rappel à votre serveur d'autorisation OAuth 2.0
<a name="identity-update-credential-provider"></a>

Pour empêcher les redirections non autorisées, ajoutez l'URL de rappel récupérée depuis [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)ou [GetOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_GetOauth2CredentialProvider.html)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 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
<a name="identity-quick-start-agent"></a>

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
<a name="identity-quick-start-agent-code"></a>

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

**Note**  
[Pour un exemple d'implémentation d'un serveur de rappel local pour gérer la [liaison de session](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html), reportez-vous au fichier oauth2\_callback\_server.py](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/oauth2_callback_server.py) 

## Étape 4 : Déployer l'agent sur AgentCore Runtime
<a name="identity-quick-start-deploy"></a>

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
<a name="identity-quick-start-iam-policy"></a>

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
<a name="identity-quick-start-invoke"></a>

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.

**Important**  
Le `--user-id` paramètre utilise le chemin de l'`GetWorkloadAccessTokenForUserId`API, qui traite l'userID comme une chaîne opaque sans le vérifier par rapport à l'identité authentifiée de l'utilisateur final. Cela convient aux scénarios de démarrage rapide et de développement dans lesquels vous ne disposez pas d'un jeton IdP. Pour les déploiements de production dans lesquels un JWT identifie l'utilisateur final, utilisez plutôt le chemin JWT-based d'authentification (`GetWorkloadAccessTokenForJWT`), qui valide l'émetteur, la signature et l'expiration du jeton. Pour plus d'informations, voir [Obtenir un jeton d'accès à la charge](get-workload-access-token.md) de travail.

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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/oauth2-authorization-url-session-binding.html). 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.

**Note**  
Si vous interrompez un appel sans avoir complété l'autorisation, vous devrez peut-être demander une nouvelle URL à l'aide d'un nouvel identifiant de session (`--session-id`paramètre).

### Débogage
<a name="identity-quick-start-debugging"></a>

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écution`agentcore deploy`.

## Nettoyage
<a name="identity-quick-start-cleanup"></a>

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é
<a name="identity-quick-start-security"></a>

Lorsque vous travaillez avec des informations d'identité :

1.  Ne **codez jamais vos informations d'identification en dur dans le code** de votre agent

1.  **Utilisez des variables d'environnement ou Amazon SageMaker AI** pour les informations sensibles

1.  **Appliquer le principe du moindre privilège** lors de la configuration des autorisations IAM

1.  **Alternez régulièrement les informations d'identification** pour les services externes

1.  **Auditez les journaux d'accès** pour surveiller l'activité des agents

1.  **Mettre en œuvre une gestion appropriée des erreurs** en cas d'échec d'authentification