# Authentifier et autoriser avec l'authentification entrante et l'authentification sortante
[Cette section explique comment implémenter l'authentification et l'autorisation pour le runtime de votre agent à l'aide de jetons porteurs OAuth et JWT avec Identity. AgentCore ](identity.md) Vous apprendrez à configurer des groupes d'utilisateurs de Cognito, à configurer le runtime de votre agent pour l'authentification JWT (Inbound Auth) et à implémenter l' OAuth-based accès à des ressources tierces (Outbound Auth).
Pour un exemple complet, voir[https://github.com/awslabs/amazon-bedrock-agentcore-samples/](https://github.com/awslabs/amazon-bedrock-agentcore-samples/).
Pour plus d'informations sur l'utilisation d'OAuth avec un serveur MCP, voir [Déployer des serveurs MCP](runtime-mcp.md) dans Runtime. AgentCore
Amazon Bedrock AgentCore Runtime fournit deux mécanismes d'authentification pour les agents hébergés :
**Authentification IAM SigV4**
Le mécanisme d'authentification et d'autorisation par défaut qui fonctionne automatiquement sans configuration supplémentaire, comme les autres AWS API.
**X-Amzn-Bedrock-AgentCore-Runtime-User-Id En-tête**
Si votre solution nécessite que l'agent hébergé récupère les jetons OAuth pour le compte des utilisateurs finaux (en utilisant le code d'autorisation Grant), vous pouvez spécifier l'identifiant de l'utilisateur en incluant l'`X-Amzn-Bedrock-AgentCore-Runtime-User-Id`en-tête dans vos demandes. Cet en-tête utilise le `GetWorkloadAccessTokenForUserId` chemin en interne.
L'invocation InvokeAgentRuntime avec le `X-Amzn-Bedrock-AgentCore-Runtime-User-Id header` nécessitera une nouvelle action IAM :`bedrock-agentcore:InvokeAgentRuntimeForUser`, en plus de l'action existante`bedrock-agentcore:InvokeAgentRuntime`.
**Quand utiliser cet en-tête par rapport à l'authentification JWT Bearer Token**
Cet en-tête est conçu pour les cas d'utilisation suivants :
+ **Entreprises clientes dont les identifiants utilisateur sont gérés par le client :** Organisations qui gèrent leurs propres chaînes d'identité utilisateur et doivent les transmettre à Identity pour la liaison des informations AgentCore d'identification.
+ **Scénarios de développement et de démarrage rapide** : créateurs qui ne disposent pas encore d'un jeton IdP et qui ont besoin d'un moyen rapide pour tester des flux d'informations d'identification adaptés à l'utilisateur.
Pour les déploiements de production où un fournisseur d'identité est configuré, utilisez plutôt l'authentification [JWT Bearer Token](#oauth-sample-overview). Le chemin JWT (`GetWorkloadAccessTokenForJWT`) valide l'émetteur, la signature et l'expiration du jeton, fournissant une preuve cryptographique de l'identité de l'utilisateur. Le chemin `X-Amzn-Bedrock-AgentCore-Runtime-User-Id` d'en-tête ne vérifie pas l'UserID par rapport à l'identité authentifiée de l'utilisateur final. Il dépend de la charge de travail des appels pour transmettre la valeur correcte et de vos politiques IAM pour limiter les personnes autorisées à la fournir.
**Bonnes pratiques de sécurité pour les X-Amzn-Bedrock-AgentCore-Runtime-User-Id en-têtes**
**Astuce**
Pour une vue consolidée de toutes les recommandations de sécurité relatives à Runtime, consultez [la section Bonnes pratiques en matière de sécurité pour AgentCore Runtime](runtime-security-best-practices.md).
Étant donné AgentCore que la valeur d'en-tête est traitée comme un identifiant opaque sans la vérifier par rapport à une identité authentifiée, vous devez appliquer les contrôles suivants pour maintenir la limite de sécurité :
+ **Restreindre l'autorisation IAM** : seuls les principaux fiables doivent avoir cette autorisation. `bedrock-agentcore:InvokeAgentRuntimeForUser` Étendez cette autorisation à des ressources d'exécution spécifiques à l'aide des conditions de ressources IAM. Ne l'accordez pas de manière générale par le biais de politiques gérées ou de déclarations de ressources génériques.
+ **Dériver l'identifiant utilisateur du principal authentifié** — La valeur de l'identifiant utilisateur doit être dérivée du contexte du principal authentifié (par exemple, l'identité de l'appelant IAM ou les demandes de jeton d'utilisateur) plutôt que d'accepter des valeurs arbitraires fournies par le client. Cela empêche un utilisateur authentifié de se faire passer pour un autre utilisateur en spécifiant manuellement un autre utilisateur. `user-id`
+ **Implémenter la journalisation des audits** : enregistrez la relation entre le principal IAM authentifié (à partir du contexte SigV4) et la `user-id` valeur transmise. AWS CloudTrail À utiliser pour surveiller `InvokeAgentRuntime` les appels qui incluent le `runtimeUserId` paramètre.
+ **Refuser l'en-tête dans des contextes non fiables** : pour les environnements d'exécution où la délégation d'identifiant utilisateur n'est pas nécessaire, refusez explicitement l'`bedrock-agentcore:InvokeAgentRuntimeForUser`action dans les politiques IAM pour empêcher l'acceptation de l'en-tête :
```
{
"Statement": [
{
"Sid": "DenyUserIdDelegation",
"Effect": "Deny",
"Action": "bedrock-agentcore:InvokeAgentRuntimeForUser",
"Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:runtime/*"
}
]
}
```
**Authentification par jeton JWT Bearer**
Vous pouvez configurer le runtime de votre agent pour qu'il accepte les jetons porteurs JWT en fournissant la configuration de l'autorisateur lors de la création de l'agent.
Cette configuration inclut :
+ URL de découverte : chaîne qui doit correspondre au modèle des URL `^.+/\.well-known/openid-configuration$` de découverte d'OpenID Connect
+ Audiences autorisées : liste des audiences autorisées qui seront validées par rapport à la réclamation AUD contenue dans le jeton JWT
+ Clients autorisés : liste des identifiants clients autorisés qui seront validés par rapport à la réclamation client\_id dans le jeton JWT
+ Portées autorisées : liste des étendues autorisées qui seront validées par rapport à la réclamation de portée contenue dans le jeton JWT. Le champ `allowedScopes` d'autorisation sera configuré sous la forme d'une liste de chaînes.
+ Réclamations personnalisées requises - Liste des réclamations requises qui seront validées par rapport au nom et à la valeur de la réclamation contenus dans le jeton JWT entrant. Pour plus de détails sur la configuration de l'autorisateur, voir [Configurer l'autorisateur JWT entrant](inbound-jwt-authorizer.md)
**Note**
Un AgentCore Runtime peut prendre en charge l'authentification entrante basée sur IAM SigV4 ou JWT Bearer Token, mais pas les deux simultanément. Vous pouvez toujours créer différentes versions de votre AgentCore Runtime et les configurer pour différents types d'autorisations entrantes. Lorsque vous créez un environnement d'exécution avec Amazon Bedrock AgentCore, une identité de charge de travail est créée automatiquement pour votre environnement d'exécution avec le service AgentCore Identity.
**Topics**
+ [Limitez les appels entrants IAM (SigV4) à votre passerelle](#runtime-restrict-iam-gateway)
+ [Exemple d'autorisation entrante JWT et d'accès sortant OAuth](#oauth-sample-overview)
+ [Conditions préalables](#oauth-prerequisites)
+ [Étape 1 : Créez votre projet d'agent](#prepare-agent)
+ [Étape 2 : Configuration AWS Groupe d'utilisateurs Cognito et ajout d'un utilisateur](#setup-cognito)
+ [Étape 3 (facultatif) : présentez votre environnement d'exécution à l'aide d'une AgentCore passerelle](#runtime-front-with-gateway)
+ [Étape 4 : Déployez votre agent](#deploy-agent)
+ [Étape 5 : utilisez le jeton porteur pour invoquer votre agent](#oauth-invoke-agent)
+ [Réponses aux erreurs OAuth](#oauth-error-responses)
+ [Étape 6 : configurer votre agent pour accéder aux outils à l'aide d'OAuth](#oauth-outbound-access)
+ [Étape 7 : (Facultatif) Propagation d'un jeton JWT vers Runtime AgentCore](#oauth-propagate-jwt-token)
+ [Résolution des problèmes](#troubleshooting)
## Limitez les appels entrants IAM (SigV4) à votre passerelle
Vous pouvez équiper votre AgentCore environnement d'exécution d'une AgentCore passerelle afin que celle-ci devienne le point d'entrée unique et régi vers l'environnement d'exécution. Vous bénéficiez ainsi d'une autorisation basée sur des règles, d'Amazon Bedrock Guardrails, d'intercepteurs de requêtes et de réponses et d'une observabilité unifiée, le tout appliqué en dehors de l'environnement de l'agent. Pour en savoir plus sur les raisons et sur la manière de le configurer, voir [Façonner votre environnement d'exécution avec une AgentCore passerelle](runtime-security-best-practices.md#security-bp-front-with-gateway).
Mais cela n'est utile que si les appelants ne peuvent pas atteindre le moteur d'exécution en contournant directement la passerelle. Si votre environnement d'exécution utilise l'autorisation entrante IAM (SigV4) par défaut, vous pouvez limiter l'appel à la passerelle afin que le trafic atteigne le moteur d'exécution uniquement par son intermédiaire. Pour ce faire, associez à l'environnement d'exécution une politique basée sur les ressources qui limite l'invocation au rôle d'exécution de votre passerelle. La passerelle assume son rôle de service pour signer les demandes adressées au moteur d'exécution. Le rôle de passerelle est donc le principal qui invoque le moteur d'exécution. Autorisez ce rôle et ajoutez un explicite `Deny` pour tous les autres principaux afin qu'aucune autre identité ne puisse invoquer le runtime, même avec une politique permissive basée sur l'identité. Pour plus d'informations sur les politiques basées sur les ressources applicables aux environnements d'exécution, consultez les politiques d'[Amazon Resource-based Bedrock](resource-based-policies.md). AgentCore
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowOnlyGatewayRole",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID"
},
{
"Sid": "DenyOtherPrincipals",
"Effect": "Deny",
"Principal": { "AWS": "*" },
"Action": "bedrock-agentcore:InvokeAgentRuntime",
"Resource": "arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/RUNTIME_ID",
"Condition": {
"ArnNotEquals": {
"aws:PrincipalArn": "arn:aws:iam::111122223333:role/MyGatewayExecutionRole"
}
}
}
]
}
```
**Astuce**
Un explicite l'emporte `Deny` toujours sur tout`Allow`, y compris les politiques basées sur l'identité dans le même compte. Lorsque vous appuyez `Deny` sur `aws:PrincipalArn` Activé, seul le rôle d'exécution de votre passerelle peut invoquer le runtime, quelles que soient les autres autorisations existantes sur votre compte.
**Important**
Restreindre l'environnement d'exécution au rôle d'exécution de la passerelle est aussi efficace que les contrôles permettant de déterminer qui peut assumer ce rôle. Tout principal pouvant assumer le rôle d'exécution de passerelle peut invoquer le moteur d'exécution comme s'il s'agissait de la passerelle. Verrouillez le rôle en ajoutant `aws:SourceArn` des `aws:SourceAccount` conditions à la politique de confiance **du rôle d'exécution de la passerelle** afin que seule votre passerelle puisse l'assumer. Le guide de [prévention de Confused deputy](runtime-security-best-practices.md#security-bp-confused-deputy) montre la même technique appliquée au rôle d'exécution d'un environnement d'exécution ; appliquez le même schéma ici, mais définissez la politique de confiance concernant le rôle d'exécution de la passerelle et l'étendue `aws:SourceArn` de l'ARN de votre passerelle.
## Exemple d'autorisation entrante JWT et d'accès sortant OAuth
Ce guide explique le processus de configuration de l'environnement d'exécution de votre agent pour qu'il soit invoqué avec un jeton d'accès conforme à OAuth au format JWT. L'agent témoin sera autorisé à l'aide des jetons d'accès AWS Cognito. Plus tard, vous découvrirez également comment le code de l'agent peut récupérer des jetons Google au nom de l'utilisateur pour vérifier Google Drive et récupérer du contenu.
**Ce que vous allez apprendre**
Dans ce guide, vous allez apprendre à :
+ Configuration du groupe d'utilisateurs de Cognito, ajout d'un utilisateur et obtention d'un jeton porteur pour l'utilisateur
+ Configurez l'environnement d'exécution de votre agent pour utiliser le groupe d'utilisateurs Cognito à des fins d'autorisation
+ Configurez votre code d'agent pour récupérer les jetons OAuth au nom de l'utilisateur pour appeler les outils
## Conditions préalables
Avant de commencer, assurez-vous d'avoir :
+ Un AWS compte avec les autorisations appropriées
+ Compréhension de base de la programmation Python
+ Connaissance des conteneurs Docker (pour un déploiement avancé)
+ Configuration réussie d'un agent de base avec exécution
+ La dernière AWS CLI et `jq` installée
+ Compréhension de base de l'autorisation OAuth, principalement des jetons porteurs JWT, des réclamations et des différents flux de subventions
## Étape 1 : Créez votre projet d'agent
Utilisez la `agentcore create` commande pour configurer un projet d'agent squelette avec le framework de votre choix :
```
agentcore create
```
La commande vous demandera de :
+ Choisissez un framework (choisissez Strands Agents pour ce tutoriel)
+ Entrez un nom de projet
+ Configuration d’options supplémentaires
Cette commande génère :
+ Code d'agent avec le framework que vous avez sélectionné
+ Fichier de configuration `agentcore/agentcore.json`
+ `requirements.txt`avec les dépendances nécessaires
**Note**
Le code d'agent généré servira de base à la mise en œuvre de l'authentification OAuth dans les étapes suivantes.
## Étape 2 : Configuration AWS Groupe d'utilisateurs Cognito et ajout d'un utilisateur
Pour configurer un groupe d'utilisateurs Cognito et créer un utilisateur, vous allez utiliser un script shell qui automatise le processus.
Pour plus d'informations, voir [Étape 2 : Importer les modules Identity et Auth](identity-getting-started-google.md#identity-getting-started-step2).
**Pour configurer le groupe d'utilisateurs de Cognito et créer un utilisateur**
+ Créez un fichier nommé `setup_cognito.sh` avec le contenu suivant:
```
#!/bin/bash
# Create User Pool and capture Pool ID directly
export POOL_ID=$(aws cognito-idp create-user-pool \
--pool-name "MyUserPool" \
--policies '{"PasswordPolicy":{"MinimumLength":8}}' \
--region $REGION | jq -r '.UserPool.Id')
# Create App Client and capture Client ID directly
export CLIENT_ID=$(aws cognito-idp create-user-pool-client \
--user-pool-id $POOL_ID \
--client-name "MyClient" \
--no-generate-secret \
--explicit-auth-flows "ALLOW_USER_PASSWORD_AUTH" "ALLOW_REFRESH_TOKEN_AUTH" \
--region $REGION | jq -r '.UserPoolClient.ClientId')
# Create User
aws cognito-idp admin-create-user \
--user-pool-id $POOL_ID \
--username $USERNAME \
--region $REGION \
--message-action SUPPRESS > /dev/null
# Set Permanent Password
aws cognito-idp admin-set-user-password \
--user-pool-id $POOL_ID \
--username $USERNAME \
--password $PASSWORD \
--region $REGION \
--permanent > /dev/null
# Authenticate User and capture Access Token
export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
--client-id "$CLIENT_ID" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME=$USERNAME,PASSWORD=$PASSWORD \
--region $REGION | jq -r '.AuthenticationResult.AccessToken')
# Output the required values
echo "Pool id: $POOL_ID"
echo "Discovery URL: https://cognito-idp.$REGION.amazonaws.com/$POOL_ID/.well-known/openid-configuration"
echo "Client ID: $CLIENT_ID"
echo "Bearer Token: $BEARER_TOKEN"
```
Ouvrez une fenêtre de terminal et définissez les variables d'environnement suivantes :
+ {{REGION}}— la AWS région que vous souhaitez utiliser
+ {{USERNAME}}— le nom d'utilisateur du nouvel utilisateur
+ {{PASSWORD}}— le mot de passe du nouvel utilisateur
```
export REGION=us-east-1 // set your desired Region
export USERNAME=USER NAME
export PASSWORD=PASSWORD
```
Dans la fenêtre du terminal, exécutez le script :
```
source setup_cognito.sh
```
Notez le résultat du script. Vous aurez besoin de ces valeurs dans les prochaines étapes.
Ce script crée un groupe d'utilisateurs Cognito, un client de groupe d'utilisateurs, ajoute un utilisateur et génère un jeton porteur pour l'utilisateur. Le jeton est valide pendant 60 minutes par défaut.
## Étape 3 (facultatif) : présentez votre environnement d'exécution à l'aide d'une AgentCore passerelle
Vous pouvez équiper votre AgentCore environnement d'exécution d'une AgentCore passerelle afin que celle-ci devienne le point d'entrée unique et régi vers l'environnement d'exécution. Vous bénéficiez ainsi d'une autorisation basée sur des règles, d'Amazon Bedrock Guardrails, d'intercepteurs de requêtes et de réponses et d'une observabilité unifiée, le tout appliqué en dehors de l'environnement de l'agent. Pour en savoir plus sur les raisons et sur la manière de le configurer, voir [Façonner votre environnement d'exécution avec une AgentCore passerelle](runtime-security-best-practices.md#security-bp-front-with-gateway).
Si vous souhaitez créer cet environnement d'exécution, [créez la passerelle](gateway-create.md) dès maintenant, avant de déployer le moteur d'exécution à l'étape suivante. Après le déploiement, vous [ajouterez le runtime en tant que cible de passerelle](gateway-target-http-runtime.md).
Pour vous assurer que les appelants ne peuvent pas contourner la passerelle, limitez le temps d'exécution afin qu'il n'accepte que les appels provenant de cette passerelle. Vous le configurez à l'étape suivante, dans le cadre de l'autorisateur, en utilisant `allowedWorkloadConfiguration` (voir [autorisé WorkloadConfiguration : restreindre l'invocation à votre passerelle](#deploy-agent-allowed-workload)).
## Étape 4 : Déployez votre agent
**Important**
À compter **du 13 octobre 2025,** Amazon Bedrock AgentCore utilise un Service-Linked rôle (SLR) pour les autorisations d'identité des charges de travail au lieu d'exiger la configuration manuelle des politiques IAM pour les nouveaux agents.
Détails du Service-Linked rôle :
**Nom**: `AWSServiceRoleForBedrockAgentCoreRuntimeIdentity`
**Directeur du service :** `runtime-identity.bedrock-agentcore.amazonaws.com`
**Objectif :** gère l'identité de la charge de travail, les jetons d'accès et les informations d'identification OAuth
Assurez-vous que le rôle que vous utilisez pour appeler les API de AgentCore contrôle est autorisé à créer le Service-Linked rôle :
```
{
"Sid": "CreateBedrockAgentCoreIdentityServiceLinkedRolePermissions",
"Effect": "Allow",
"Action": "iam:CreateServiceLinkedRole",
"Resource": "arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity",
"Condition": {
"StringEquals": {
"iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com"
}
}
}
```
**Avantage** : le Service-Linked rôle fournit automatiquement les autorisations nécessaires pour accéder à l'identité de la charge de travail sans nécessiter de configuration manuelle des politiques.
Pour des informations détaillées sur le rôle lié au service, consultez la section Rôle lié au [service Identity](service-linked-roles.md#identity-service-linked-role).
Vous allez maintenant déployer votre agent avec l'autorisation JWT en utilisant le groupe d'utilisateurs Cognito que vous avez créé. Vous devez créer un agent avec une configuration d'autorisation. Le tableau suivant représente les différents paramètres de configuration de l'autorisateur et la manière dont nous les utilisons pour valider le jeton entrant.
| configuration\_autorisation | réclamation sous forme de jeton décodé | Remarques |
| --- | --- | --- |
| URL de découverte → émetteur | iss | L'URL de découverte doit pointer vers l'URL de l'émetteur. Cela doit correspondre à la réclamation iss dans le jeton décodé. |
| Clients autorisés | client\_id | le client\_id dans le jeton doit correspondre à l'un des clients autorisés spécifiés dans l'autorisateur |
| Public autorisé | aud | L'une des valeurs en dollars australiens réclamées par le jeton doit correspondre à l'une des audiences autorisées spécifiées dans l'autorisateur |
| autorisé WorkloadConfiguration | `internal` | Facultatif. Au lancement, utilisé pour autoriser uniquement votre AgentCore passerelle à appeler le runtime. Consultez [Restreindre l'invocation à votre passerelle](#deploy-agent-allowed-workload). |
Si client\_id et aud sont fournis, l'autorisateur d'exécution de l'agent vérifiera les deux.
### autorisé WorkloadConfiguration : limitez l'invocation à votre passerelle
Le `allowedWorkloadConfiguration` champ relatif au `customJWTAuthorizer` restreint les charges de travail de la chaîne d'identité de la demande autorisées à invoquer le runtime. Définissez la charge de travail autorisée pour votre passerelle afin que le moteur d'exécution accepte une demande uniquement lorsque sa chaîne d'identité inclut cette passerelle. C'est ainsi qu'un environnement d'exécution OAuth (JWT) garantit que le trafic n'arrive que via la passerelle que vous avez configurée à l'étape 3.
Vous indiquez les charges de travail autorisées à l'aide de l'un des champs suivants. Vous pouvez en spécifier un ou les deux : une demande est acceptée si sa chaîne d'identité correspond à une entrée dans l'un **ou** l'autre des champs, vous n'avez donc pas besoin de fournir les deux.
+ **HostingEnvironments** : liste des environnements d'hébergement dont les charges de travail sont autorisées à invoquer la cible. Chaque entrée est un objet avec un`arn`. Au lancement, le seul environnement d'hébergement pris en charge est AgentCore Gateway. Chaque environnement `arn` doit donc être un AgentCore Gateway ARN.
+ **workloadIdentities** — Liste des noms d'identité de charge de travail autorisés à appeler la cible. Le nom d'identité d'une charge de travail **n'est pas** un ARN. Il s'agit du dernier segment de l'ARN d'identité de charge de travail de la passerelle, que vous pouvez trouver dans le `workloadIdentityDetails` champ de `GetGateway` réponse. Par exemple, si tel `workloadIdentityDetails.workloadIdentityArn` est le cas`arn:aws:bedrock-agentcore:us-east-1:111122223333:workload-identity-directory/default/workload-identity/my-gateway-workload-identity`, le nom de l'identité de la charge de travail est`my-gateway-workload-identity`.
L'exemple suivant crée un environnement d'exécution d'agent qui restreint l'invocation à une AgentCore passerelle spécifique par son ARN. La spécification `hostingEnvironments` seule est le moyen le plus simple d'autoriser une passerelle :
```
{
"authorizerConfiguration": {
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_example/.well-known/openid-configuration",
"allowedClients": ["your-client-id"],
"allowedWorkloadConfiguration": {
"hostingEnvironments": [
{
"arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-id"
}
]
}
}
}
}
```
Vous pouvez également identifier la passerelle par son nom d'identité de charge de travail ou spécifier les deux champs. Lorsque les deux sont présents, une demande est autorisée si elle correspond à une entrée dans l'un ou l'autre des champs. L'`allowedWorkloadConfiguration`extrait suivant autorise deux passerelles différentes, l'une identifiée par son ARN et l'autre par le nom de son identité de charge de travail :
```
"allowedWorkloadConfiguration": {
"hostingEnvironments": [
{
"arn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway-1-id"
}
],
"workloadIdentities": [
"my-gateway-2-workload-identity"
]
}
```
**Note**
Au lancement, n'`allowedWorkloadConfiguration`est pris en charge que pour les cibles AgentCore d'exécution, et les charges de travail autorisées sont les AgentCore passerelles.
### Création et déploiement de l'environnement d'exécution de l'agent
Une fois la configuration de votre autorisateur prête, créez et déployez le runtime de l'agent. Les exemples suivants montrent comment procéder avec la AgentCore CLI ou le AWS SDK pour Python (Boto3). Notez l'ARN d'exécution de l'agent indiqué dans la sortie : vous en aurez besoin pour appeler l'agent à l'étape suivante.
**Example**
**Pour configurer et déployer votre agent**
1. Créez votre projet d'agent avec la AgentCore CLI :
```
agentcore create
```
Lorsque vous y êtes invité, choisissez votre framework (choisissez Strands Agents pour ce didacticiel).
1. Déployez votre agent :
```
agentcore deploy
```
1. Notez l'ARN d'exécution de l'agent indiqué dans la sortie. Vous en aurez besoin à l'étape suivante.
**Astuce**
Vous pouvez également exécuter la `agentcore create` commande sans indicateur pour bénéficier d'une expérience entièrement interactive qui vous guide tout au long de la configuration du projet.
1.
```
import boto3
# Create the client
client = boto3.client('bedrock-agentcore-control', region_name="us-east-1")
# Call the CreateAgentRuntime operation
response = client.create_agent_runtime(
agentRuntimeName='HelloAgent',
agentRuntimeArtifact={
'containerConfiguration': {
'containerUri': '111122223333.dkr.ecr.us-east-1.amazonaws.com/my-agent:latest'
}
},
authorizerConfiguration={
"customJWTAuthorizer": {
"discoveryUrl": 'COGNITO_DISCOVERY_URL',
"allowedClients": ['COGNITO_CLIENT_ID']
}
},
networkConfiguration={"networkMode":"PUBLIC"},
roleArn='arn:aws:iam::111122223333:role/AgentRuntimeRole',
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
```
## Étape 5 : utilisez le jeton porteur pour invoquer votre agent
Maintenant que votre agent est déployé avec l'autorisation JWT, vous pouvez l'invoquer à l'aide du jeton porteur.
**Note**
Si vous avez doté votre environnement d'exécution d'une passerelle à l'[étape 3](#runtime-front-with-gateway), ajoutez le moteur d'exécution déployé en tant que cible de passerelle avant de l'appeler (voir [Cibles AgentCore d'exécution](gateway-target-http-runtime.md)), puis appelez via le point de terminaison de passerelle illustré dans les exemples suivants, plutôt que via le point de terminaison d'exécution.
**Important**
**Important pour les utilisateurs existants : les** agents créés **avant le 13 octobre 2025** continueront d'utiliser le rôle d'exécution d'agent pour les autorisations d'identité et **exigeront** que la politique précédente soit attachée au rôle d'exécution de l'agent.
**Nouveaux agents** : pour les agents créés **le 13 octobre 2025 ou après** cette date, cette politique **n'est pas obligatoire** car les autorisations sont gérées automatiquement par le Service-Linked rôle.
```
{
"Sid": "GetAgentAccessToken",
"Effect": "Allow",
"Action": [
"bedrock-agentcore:GetWorkloadAccessToken",
"bedrock-agentcore:GetWorkloadAccessTokenForJWT",
"bedrock-agentcore:GetWorkloadAccessTokenForUserId"
],
# point to the workload identity for the runtime; the workload identity can be found in
# the GetAgentRuntime response and has your agent name in it.
"Resource": [
"arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default",
"arn:aws:bedrock-agentcore:region:account-id:workload-identity-directory/default/workload-identity/agentname-*"
]
}
```
**Invoquer l'agent**
Récupérez un jeton porteur pour l'utilisateur que vous avez créé avec Amazon Cognito.
```
# use the password and other details used when you created the cognito user
export TOKEN=$(aws cognito-idp initiate-auth \
--client-id "$CLIENT_ID" \
--auth-flow USER_PASSWORD_AUTH \
--auth-parameters USERNAME='testuser',PASSWORD='PASSWORD' \
--region us-east-1 | jq -r '.AuthenticationResult.AccessToken')
```
Procédez à l'appel de l'agent en suivant le reste des instructions suivantes.
Appelez l'agent avec OAuth.
**Example**
1.
```
// Invoke with OAuth token
export PAYLOAD='{"prompt": "hello what is 1+1?"}'
export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://bedrock-agentcore.us-east-1.amazonaws.com"
# If you fronted the runtime with a gateway (Step 3), the core endpoint URL is now your gateway URL
# export BEDROCK_AGENT_CORE_ENDPOINT_URL="https://${GATEWAY_ID}.gateway.bedrock-agentcore.us-east-1.amazonaws.com/${TARGET_NAME}"
export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/runtimes/${ESCAPED_AGENT_ARN}/invocations?qualifier=DEFAULT"
# If you fronted the runtime with a gateway (Step 3), the preceding URL works but there is also a simpler alternative:
# export INVOKE_URL="${BEDROCK_AGENT_CORE_ENDPOINT_URL}/invocations"
curl -v -X POST "${INVOKE_URL}" \
-H "Authorization: Bearer ${TOKEN}" \
-H "X-Amzn-Trace-Id: your-trace-id" \
-H "Content-Type: application/json" \
-H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: your-session-id" \
-d ${PAYLOAD}
```
1. Comme boto3 ne prend pas en charge l'invocation avec des jetons porteurs, vous devrez utiliser un client HTTP tel que la bibliothèque de requêtes en Python.
**Pour invoquer votre agent avec un jeton porteur**
1. Créez un script Python nommé `invoke_agent.py` avec le contenu suivant :
```
import requests
import urllib.parse
import json
import os
# Configuration Constants
REGION_NAME = "AWS_REGION"
# === Agent Invocation Demo ===
invoke_agent_arn = "YOUR_AGENT_ARN_HERE"
auth_token = os.environ.get('TOKEN')
print(f"Using Agent ARN from environment: {invoke_agent_arn}")
# URL encode the agent ARN
escaped_agent_arn = urllib.parse.quote(invoke_agent_arn, safe='')
# Construct the URL — invoke the runtime directly
url = f"https://bedrock-agentcore.{REGION_NAME}.amazonaws.com/runtimes/{escaped_agent_arn}/invocations?qualifier=DEFAULT"
# If you are fronting the runtime with a gateway (see Step 3), invoke through
# the gateway target instead (replace GATEWAY_ID and my-target):
# url = f"https://GATEWAY_ID.gateway.bedrock-agentcore.{REGION_NAME}.amazonaws.com/my-target/invocations"
# Set up headers
headers = {
"Authorization": f"Bearer {auth_token}",
"X-Amzn-Trace-Id": "your-trace-id",
"Content-Type": "application/json",
"X-Amzn-Bedrock-AgentCore-Runtime-Session-Id": "testsession123"
}
# Enable verbose logging for requests
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3.connectionpool").setLevel(logging.DEBUG)
invoke_response = requests.post(
url,
headers=headers,
data=json.dumps({"prompt": "Hello what is 1+1?"})
)
# Print response in a safe manner
print(f"Status Code: {invoke_response.status_code}")
print(f"Response Headers: {dict(invoke_response.headers)}")
# Handle response based on status code
if invoke_response.status_code == 200:
response_data = invoke_response.json()
print("Response JSON:")
print(json.dumps(response_data, indent=2))
elif invoke_response.status_code >= 400:
print(f"Error Response ({invoke_response.status_code}):")
error_data = invoke_response.json()
print(json.dumps(error_data, indent=2))
else:
print(f"Unexpected status code: {invoke_response.status_code}")
print("Response text:")
print(invoke_response.text[:500])
```
1. Remplacez {{AWS\_REGION}} par la AWS région que vous utilisez. à l'étape 3.
1. {{YOUR\_AGENT\_ARN\_HERE}}Remplacez-le par l'ARN d'exécution réel de votre agent indiqué à l'étape 3.
1. Exécutez le script :
```
python invoke_agent.py
```
## Réponses aux erreurs OAuth
OAuth-configured les agents respectent les [normes d'authentification RFC 6749 (OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749)). Lorsque l'authentification est absente, le service renvoie une réponse 401 Unauthorized avec un WWW-Authenticate en-tête (conformément à la [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235)), permettant aux clients de découvrir les points de terminaison du serveur d'autorisation via l'API. GetRuntimeProtectedResourceMetadata
### 401 Non autorisé - Authentification manquante
Lorsqu'aucun jeton porteur n'est fourni dans l'en-tête d'autorisation, la réponse est la suivante :
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
```
L'`resource_metadata`URL figurant dans l' WWW-Authenticate en-tête pointe vers l'API Protected Resource Metadata (PRM). L'API PRM permet aux clients de découvrir quels serveurs d'autorisation protègent cet agent et leurs URL de point de terminaison OAuth.
**Note**
Vous devez pré-enregistrer votre client OAuth dans Cognito (via la console AWS ou la CLI) pour obtenir un `client_id` avant d'utiliser les points de terminaison découverts. Amazon Cognito ne prend pas en charge l'enregistrement dynamique des clients (RFC 7591).
## Étape 6 : configurer votre agent pour accéder aux outils à l'aide d'OAuth
Dans cette section, vous allez apprendre à connecter le code de votre agent aux fournisseurs AgentCore d'informations d'identification pour un accès sécurisé aux ressources externes à l'aide de l'authentification OAuth2.
L'exemple suivant montre comment votre agent exécuté dans Agent Runtime peut demander le consentement OAuth des utilisateurs, leur permettant de s'authentifier avec leur compte Google et d'autoriser l'agent à accéder à leur contenu Google Drive.
Pour plus d'informations sur la configuration de l'identité, voir [Commencer avec AgentCore Identity](identity-getting-started.md).
### Étape 6.1 : Configuration des fournisseurs d'informations d'identification
Pour configurer un fournisseur d'informations d'identification Google, vous devez :
1. Enregistrez votre application auprès de Google pour obtenir l'ID client et le secret du client
1. Créez un fournisseur d'informations d'identification OAuth à l'aide de la CLI. AWS Remplacez {{your-client-id}} et {{your-client-secret}} par votre identifiant client Google OAuth2 actuels et votre code secret client :
```
OAUTH2_CREDENTIAL_PROVIDER_RESPONSE=$(aws bedrock-agentcore-control create-oauth2-credential-provider \
--name "google-provider" \
--credential-provider-vendor "GoogleOauth2" \
--oauth2-provider-config-input '{
"googleOauth2ProviderConfig": {
"clientId": "your-client-id",
"clientSecret": "your-client-secret"
}
}' \
--output json)
OAUTH2_CALLBACK_URL=$(echo $OAUTH2_CREDENTIAL_PROVIDER_RESPONSE | jq -r '.callbackUrl')
echo "OAuth2 Callback URL: $OAUTH2_CALLBACK_URL"
```
**Note**
Obtenez le résultat `callbackUrl` de la [CreateOauth2CredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreateOauth2CredentialProvider.html)réponse et ajoutez l'URI à la liste des URI de redirection de votre application Google. L'URL de rappel doit ressembler à : https://bedrock-agentcore.us-east-1.amazonaws.com/identities/oauth2/callback/ \*\*\*\*\*\*\*\*-\*\*\*\*-\*\*\*\*-\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*
Assurez-vous que votre rôle d'invocation dispose des autorisations nécessaires pour accéder au fournisseur d'informations d'identification.
### Étape 6.2 : Permettre à l'agent de lire le contenu de Google Drive
Créez un outil avec les annotations du SDK principal de l'agent, comme indiqué dans l'exemple suivant pour lancer automatiquement le processus OAuth en trois étapes. Lorsque votre agent invoque cet outil, les utilisateurs sont invités à ouvrir l'URL d'autorisation dans leur navigateur et à autoriser l'agent à accéder à leur Google Drive.
```
import asyncio
from bedrock_agentcore.identity.auth import requires_access_token, requires_api_key
# This annotation helps agent developer to obtain access tokens from external applications
@requires_access_token(
provider_name="google-provider",
scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"], # Google OAuth2 scopes
auth_flow="USER_FEDERATION", # 3LO flow
on_auth_url=lambda x: print("Copy and paste this authorization url to your browser: ", x), # prints authorization URL to console
force_authentication=True,
callback_url='insert_oauth2_callback_url_for_session_binding'
)
async def read_from_google_drive(*, access_token: str):
print(access_token) #You can see the access_token
# Make API calls...
main(access_token)
asyncio.run(read_from_google_drive(access_token=""))
```
**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 à [https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/03-AgentCore-identity/05-Outbound_Auth_3lo/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)
**Que se passe-t-il dans les coulisses**
Lorsque ce code s'exécute, le processus suivant se produit :
1. Agent Runtime autorise le jeton entrant conformément à l'autorisateur configuré.
1. Agent Runtime échange ce jeton contre un jeton d'accès à la charge de travail via `bedrock-agentcore:GetWorkloadAccessTokenForJWT` l'API et le transmet au code de votre agent via l'en-tête `WorkloadAccessToken` de charge utile.
1. Lors de l'invocation de l'outil, votre agent utilise ce jeton d'accès à la charge de travail pour appeler l'API Token Vault `bedrock-agentcore:GetResourceOauth2Token` et générer une URL d'authentification 3LO.
1. Votre agent envoie cette URL à l'application cliente comme indiqué dans la `on_auth_url` méthode.
1. L'application cliente présente cette URL à l'utilisateur, qui autorise l'agent à accéder à son compte Google Drive.
1. AgentCore Le service d'identité reçoit et met en cache en toute sécurité le jeton d'accès Google jusqu'à son expiration, ce qui permet à l'utilisateur de demander ultérieurement à utiliser ce jeton sans que celui-ci ait à donner son consentement pour chaque demande.
**Note**
AgentCore Identity Service stocke le jeton d'accès Google dans le coffre à AgentCore jetons en utilisant l'identité de la charge de travail de l'agent et l'ID utilisateur (provenant du jeton JWT entrant, tel que le jeton AWS Cognito) comme clé de liaison, éliminant ainsi les demandes de consentement répétées jusqu'à l'expiration du jeton Google.
## Étape 7 : (Facultatif) Propagation d'un jeton JWT vers Runtime AgentCore
Vous pouvez éventuellement transmettre un en-tête d'autorisation à un AgentCore environnement d'exécution pour extraire des revendications. Cela peut être fait en utilisant la configuration de la liste d'autorisation des en-têtes de demande. Pour de plus amples informations, veuillez consulter [RequestHeaderConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_RequestHeaderConfiguration.html).
### Étape 7.1 : Modifiez le code de votre agent pour lire les en-têtes
Au cours de cette étape, vous apportez des modifications au code de votre agent afin de pouvoir décoder et extraire les revendications d'un jeton JWT à l'aide de la bibliothèque PyJWT.
**requirements.txt**
Ajoutez une dépendance PyJWT au `requirements.txt` fichier dans votre projet généré.
```
PyJWT
```
**Mettez à jour votre code d'agent**
Modifiez le fichier d'agent principal de votre projet généré (généralement `src/main.py` ou similaire, selon le framework que vous avez choisi) comme indiqué dans le code suivant. Vous pouvez ignorer la validation de la signature du jeton ici puisqu'elle a déjà été validée par AgentCore Runtime lorsque l'autorisation entrante a été effectuée.
```
import jwt
import json
....
@app.entrypoint
def invoke(payload, context):
auth_header = context.request_headers.get('Authorization')
if not auth_header:
return None
# Remove "Bearer " prefix if present
token = auth_header.replace('Bearer ', '') if auth_header.startswith('Bearer ') else auth_header
try:
# Skip signature validation as agent runtime has validated the token already.
claims = jwt.decode(token, options={"verify_signature": False})
app.logger.info("Claims: %s", json.dumps(claims))
except jwt.InvalidTokenError as e:
app.logger.exception("Invalid JWT token: %s", e)
.....
```
### Étape 7.2 : Création de l'agent avec la liste d'autorisation d'en-tête de demande
Utilisez la AgentCore CLI pour configurer l'agent avec l'en-tête de demande allowlist. Accédez au répertoire de projet que vous avez généré et exécutez :
```
agentcore create --name HelloAgent --framework Strands --model-provider Bedrock --memory none
# Now deploy the agent runtime
agentcore deploy
```
**Note**
La AgentCore CLI crée la structure du projet et les fichiers de configuration. Ajustez la configuration de l'agent `agentcore/agentcore.json` selon les besoins en fonction de votre choix de framework.
### Étape 7.3 : Invoquez votre agent
[Invoquez](#oauth-invoke-agent) votre agent en utilisant OAuth et vous devriez voir les réclamations dans les journaux de votre agent. CloudWatch
## Résolution des problèmes
### Comment résoudre les problèmes liés aux jetons
Si vous rencontrez des problèmes avec l'authentification par jeton, vous pouvez décoder le jeton pour inspecter son contenu :
```
echo "$TOKEN" | cut -d '.' -f2 | tr '_-' '/+' | awk '{ l=4 - length($0)%4; if (l<4) printf "%s", $0; for (i=0; i