View a markdown version of this page

Obtenir un jeton d'accès à la charge - Amazon Bedrock AgentCore
Qu'est-ce qu'un jeton d'accès à une charge de travail ?Comment Runtime et Gateway obtiennent automatiquement des jetonsComment récupérer manuellement les jetons d'accès à la charge de travailContrôles de sécurité pour les GetWorkloadAccessTokenForUserIdAPI

Obtenir un jeton d'accès à la charge

Il est essentiel de comprendre ce que sont les jetons d'accès aux charges de travail, comment les obtenir et les aspects de sécurité liés à leur utilisation pour créer des applications d'agent sécurisé. Cette section couvre les concepts clés et les modèles de mise en œuvre que vous devez connaître.

Qu'est-ce qu'un jeton d'accès à une charge de travail ?

Un jeton d'accès à la charge de travail est un jeton d'accès opaque AWS signé qui permet aux agents d'accéder à des AgentCore services de première partie, tels que les fournisseurs d'identifiants sortants. Runtime fournit automatiquement des jetons d'accès à la charge de travail aux instances d'exécution des agents sous forme d'en-têtes de charge utile, éliminant ainsi le besoin de gestion manuelle des jetons dans la plupart des scénarios.

Principales caractéristiques

  • First-party services uniquement — Les jetons d'accès à la charge de travail sont exclusivement destinés à accéder aux AgentCore services de AWS première partie et ne peuvent pas être utilisés pour des services externes

  • Livraison automatique — Runtime et Gateway fournissent automatiquement ces jetons aux agents lors de l'exécution

  • Sécurité dès la conception : les identités des Runtime-managed agents ne peuvent pas récupérer directement les jetons d'accès à la charge de travail, ce qui empêche leur extraction et leur utilisation abusive

  • Liaison de l'identité de l'utilisateur et de l'agent : les jetons contiennent à la fois l'identité de l'utilisateur et les informations d'identité de l'agent pour un accès sécurisé aux informations d'identification

Comment Runtime et Gateway obtiennent automatiquement des jetons

Lorsqu'un agent est invoqué via AgentCore Runtime ou Gateway avec authentification entrante, le service gère automatiquement la génération de jetons d'accès à la charge de travail :

  1. Runtime valide le jeton OAuth du fournisseur d'identité entrant (émetteur, signature)

  2. Runtime extrait les demandes de l'émetteur et des sous-demandes du jeton OAuth représentant l'identité de l'utilisateur

  3. Runtime récupère l'identité de la charge de travail associée à l'agent

  4. Le runtime appelle à la fois GetWorkloadAccessTokenForJWT avec l'identité de l'utilisateur et l'identité de la charge de travail de l'agent

  5. Le runtime transmet le jeton d'accès à la charge de travail au code de l'agent dans le cadre de l'en-tête de charge utile d'invocation

Ce processus automatique garantit que les agents reçoivent des jetons correctement définis sans intervention manuelle.

Comment récupérer manuellement les jetons d'accès à la charge de travail

Il existe deux modèles à utiliser pour récupérer le jeton d'accès à la charge de travail en fonction de la manière dont vous êtes en mesure d'identifier l'utilisateur final de l'agent :

Modèle 1 : JWT-based identification (recommandé pour la production)

Si l'appelant de l'agent possède un JWT émis par un fournisseur d'identité pour l'utilisateur final, demandez un jeton d'accès à la charge de travail en utilisant. GetWorkloadAccessTokenForJWT Lorsque vous fournissez un JWT, AgentCore Identity valide le jeton pour s'assurer qu'il est correctement signé et qu'il n'est pas expiré, et utilise ses revendications « iss » et « sub » pour identifier de manière unique l'utilisateur. Les informations d'identification stockées par l'agent au nom de l'utilisateur sont associées à cette identité vérifiée par cryptographie, et les futures récupérations nécessitent un jeton d'accès à la charge de travail valide portant la même identité.

Utilisez ce modèle lorsque :

  • Votre application s'intègre à un fournisseur d'identité (Cognito, Auth0, Okta, etc.)

  • Vous avez besoin d'une preuve cryptographique de l'identité de l'utilisateur final

  • Vous êtes en train de déployer vers la production

Schéma 2 : UserId-based identification

Si l'appelant de l'agent ne possède pas de JWT identifiant l'utilisateur final, demandez un jeton d'accès à la charge de travail à l'GetWorkloadAccessTokenForUserIdaide d'une chaîne unique identifiant l'utilisateur.

Utilisez ce modèle lorsque :

  • Votre application gère ses propres identifiants utilisateur et vous devez transmettre les chaînes UserID gérées par le client à Identity AgentCore

  • Vous êtes dans un scénario de développement ou de démarrage rapide dans lequel aucun jeton IdP n'est encore disponible

  • L'architecture de votre entreprise résout l'identité des utilisateurs en amont et transmet un identifiant fiable à la charge de travail de l'agent

Compromis : la plateforme traite l'UserID comme une chaîne opaque et ne peut pas le vérifier par rapport à une identité d'utilisateur final authentifiée. La liaison de sécurité repose sur le fait que la charge de travail appelante transmet le bon userID et sur le périmètre approprié des politiques IAM. Voir Contrôles de sécurité pour les GetWorkloadAccessTokenForUserIdAPI pour les contrôles recommandés.

Exemples de code

Les exemples ci-dessous illustrent l'utilisation du AgentCore SDK pour récupérer un jeton d'accès à une charge de travail à l'aide des deux méthodes suivantes :

from bedrock_agentcore.services.identity import IdentityClient

identity_client= IdentityClient(“us-east-1”)# Pattern 1 (recommended): Obtain a token using a JWT containing the identity of the end user.
# AgentCore Identity validates the JWT signature, issuer, and expiry.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_token= “insert-jwt-here”)# Pattern 2: Obtain a token using a string representing the identity of the end user.
# Use this when a JWT is not available. The platform does not verify this string.
workload_access_token= identity_client.get_workload_access_token(workload_name= “my-demo-agent”, user_id= “insert-user-name-or-identifier”)

Contrôles de sécurité pour les GetWorkloadAccessTokenForUserIdAPI

L'GetWorkloadAccessTokenForUserIdAPI accepte une chaîne d'identifiant utilisateur fournie par l'appelant et émet un jeton d'accès à la charge de travail limité à cette paire utilisateur-agent. Cette API est conçue pour aider les entreprises clientes qui ont besoin de transmettre des chaînes UserID gérées par le client et les créateurs qui ne disposent pas de jetons de fournisseur d'identité (IdP) disponibles pendant le développement.

Important

Lorsque vous l'utilisezGetWorkloadAccessTokenForUserId, la plateforme traite la userId valeur comme une chaîne opaque et ne la vérifie pas par rapport à l'identité authentifiée de l'utilisateur final. Le lien de sécurité repose entièrement sur le fait que la charge de travail appelante transmet le bon userID et sur la définition appropriée de vos politiques IAM. Si votre application a accès à un JWT identifiant l'utilisateur final, utilisez-le GetWorkloadAccessTokenForJWT plutôt, qui valide l'émetteur, la signature et l'expiration du jeton avant d'émettre un jeton d'accès à la charge de travail.

L'GetWorkloadAccessTokenForUserIdAPI met en œuvre plusieurs contrôles de sécurité pour empêcher tout accès non autorisé :

  • Validation de l'identité de la charge de travail : l'API vérifie que l'identité demandeuse est autorisée à agir au nom de l'identité de charge de travail spécifiée

  • Service-managed restriction d'identité — Runtime-managed et les identités Gateway-managed de charge de travail ne peuvent pas récupérer directement les jetons. Cela empêche les agents d'extraire des jetons à des fins d'utilisation abusive

  • Exigences relatives aux autorisations IAM — Les appelants doivent disposer des autorisations IAM appropriées, notamment, GetWorkloadAccessToken et GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT

  • Portée des jetons : les jetons sont limités à une paire utilisateur-agent spécifique, ce qui garantit que les informations d'identification stockées auprès d'un utilisateur ne sont pas accessibles à un autre

  • Partitionnement des identifiants utilisateur pour plusieurs fournisseurs d'identité : lorsque vous utilisez plusieurs fournisseurs d'identité, partitionnez vos identifiants utilisateur selon le modèle provider_id+user_id afin d'éviter les collisions entre les différents fournisseurs. Par exemple, utiliser cognito+user123 et auth0+user123 distinguer les utilisateurs ayant le même identifiant parmi différents fournisseurs d'identité

Contrôles de sécurité recommandés

Étant donné que la plateforme ne peut pas vérifier la chaîne UserID, il vous incombe de garantir l'intégrité de la valeur transmise à cette API. Appliquez les commandes suivantes :

  • Préférez GetWorkloadAccessTokenForJWT lorsqu'un JWT est disponible : le JWT-based chemin valide l'émetteur et la signature du jeton, fournissant ainsi une preuve cryptographique de l'identité de l'utilisateur. À utiliser GetWorkloadAccessTokenForUserId uniquement lorsqu'un JWT n'est pas disponible.

  • Dérivez l'UserID d'une source fiable : la valeur UserID doit être dérivée du contexte du principal authentifié (par exemple, l'identité de l'appelant IAM, les attributs de session ou une couche de résolution d'identité en amont) plutôt que d'accepter des valeurs arbitraires fournies par le client. Cela empêche un appelant authentifié de se faire passer pour un autre utilisateur.

  • Restreindre l'autorisation IAM : seuls les principaux fiables doivent avoir cette autorisation. bedrock-agentcore:GetWorkloadAccessTokenForUserId Étendez cette autorisation à des ressources d'identité de charge de travail spécifiques. 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.

  • Refuser GetWorkloadAccessTokenForUserId là où cela n'est pas nécessaire : pour les charges de travail pour lesquelles un JWT est toujours disponible, refusez explicitement l'action dans les politiques IAM afin d'empêcher l'utilisation du chemin UserID :

    {
   "Statement": [
      {
         "Sid": "DenyForUserIdAccess",
         "Effect": "Deny",
         "Action": "bedrock-agentcore:GetWorkloadAccessTokenForUserId",
         "Resource": "arn:aws:bedrock-agentcore:REGION:ACCOUNT_ID:workload-identity-directory/default"
      }
   ]
}

  • Implémenter la journalisation des audits : enregistrez la relation entre le principal IAM authentifié et la valeur UserID transmise. AWS CloudTrail À utiliser pour surveiller les GetWorkloadAccessTokenForUserId appels et détecter les valeurs d'userID inattendues.

Si vous rencontrez le message d'erreur « WorkloadIdentity  est lié à un service et ne peut pas récupérer de jeton d'accès par l'appelant », cela indique que l'identité de la charge de travail est gérée par Runtime ou Gateway et qu'il est impossible de récupérer les jetons directement. Cette restriction permet de maintenir les limites de sécurité et d'empêcher l'accès non autorisé par jeton.

Pour des contrôles de sécurité supplémentaires, vous pouvez mettre en œuvre des politiques d'accès précises afin de limiter les identités de charge de travail pouvant accéder à des fournisseurs d'informations d'identification spécifiques. Pour plus d'informations, voir Diminuer l'accès aux fournisseurs d'informations d'identification par identité de charge de travail.