View a markdown version of this page

Obtenir un jeton d'accès aux charges de travail - Base rocheuse de l'Amazonie AgentCore
Qu'est-ce qu'un jeton d'accès à la 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 GetWorkloadAccessTokenForUserId API

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.

Obtenir un jeton d'accès aux charges de travail

Il est essentiel de comprendre ce que sont les jetons d'accès à la charge de travail, comment les obtenir et les aspects de sécurité liés à leur utilisation pour créer des applications d'agent sécurisées. 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 à la 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 internes, tels que des fournisseurs d'informations d'identification sortants. Runtime fournit automatiquement des jetons d'accès à la charge de travail aux instances d'exécution de l'agent sous forme d'en-têtes de charge utile, éliminant ainsi la nécessité d'une 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 AWS à AgentCore des services propriétaires 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 des informations d'identité de l'utilisateur et 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 appelé 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 l'émetteur et les sous-réclamations à partir du jeton OAuth représentant l'identité de l'utilisateur

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

  4. L'exécution invoque à la fois l'identité GetWorkloadAccessTokenForJWT de l'utilisateur et l'identité de la charge de travail de l'agent

  5. Le moteur d'exécution 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élimités 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, selon la manière dont vous pouvez identifier l'utilisateur final de l'agent :

Schéma 1 : JWT-based identification (recommandé pour la production)

Si l'appelant de l'agent dispose d'un JWT émis par un fournisseur d'identité pour l'utilisateur final, demandez un jeton d'accès à la charge de travail à l'aide de. GetWorkloadAccessTokenForJWT Lorsque vous fournissez un JWT, AgentCore Identity valide le jeton pour s'assurer qu'il est correctement signé et qu'il n'a pas expiré, et utilise ses revendications « iss » et « sub » pour identifier l'utilisateur de manière unique. Les informations d'identification stockées par l'agent pour le compte de l'utilisateur sont associées à cette identité vérifiée par cryptographie, et les futures extractions 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 effectuez un déploiement en production

Schéma 2 : UserId-based identification

Si l'appelant de l'agent ne dispose pas d'un 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 des chaînes d'ID utilisateur 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

  • Votre architecture d'entreprise résout l'identité des utilisateurs en amont et transmet un identifiant sécurisé à la charge de travail de l'agent

Compromis : la plateforme traite l'ID utilisateur 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 l'ID utilisateur correct et que les politiques IAM sont définies de manière appropriée. Voir Contrôles de sécurité pour les GetWorkloadAccessTokenForUserId API 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 à la charge de travail à l'aide de ces deux méthodes :

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 GetWorkloadAccessTokenForUserId API

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 d'ID utilisateur gérées par le client et les créateurs qui ne disposent pas de jetons de fournisseur d'identité (IdP) 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 à une identité d'utilisateur final authentifiée. La liaison de sécurité dépend entièrement de la charge de travail des appelants qui transmet l'ID utilisateur correct et de la définition appropriée de la portée de vos politiques IAM. Si votre application a accès à un JWT identifiant l'utilisateur final, utilisez-le à la GetWorkloadAccessTokenForJWT place, 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 pour le compte 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 les jetons directement. 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, y compris, GetWorkloadAccessToken et GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT

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

  • Partitionnement des ID utilisateur pour plusieurs fournisseurs d'identité — Lorsque vous utilisez plusieurs fournisseurs d'identité, partitionnez vos ID utilisateur selon le modèle provider_id+user_id pour é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 est de votre responsabilité 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 une preuve cryptographique de l'identité de l'utilisateur. À utiliser GetWorkloadAccessTokenForUserId uniquement lorsqu'un JWT n'est pas disponible.

  • Dérivez l'ID utilisateur à partir d'une source fiable  : la valeur de l'identifiant utilisateur 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 responsables de confiance doivent disposer de 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 d'instructions 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 de l'ID utilisateur :

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

  • Implémentez la journalisation des audits  : enregistrez la relation entre le principal IAM authentifié et la valeur UserID transmise. Utilisez-le AWS CloudTrail pour surveiller les GetWorkloadAccessTokenForUserId appels et détecter les valeurs d'ID utilisateur inattendues.

Si vous rencontrez l'erreur « WorkloadIdentity  est lié à un service et ne peut pas récupérer un jeton d'accès par l'appelant », cela signifie que l'identité de la charge de travail est gérée par Runtime ou Gateway et ne peut pas 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é aux jetons.

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 qui peuvent accéder à des fournisseurs d'informations d'identification spécifiques. Pour plus d'informations, voir Limiter l'accès aux fournisseurs d'informations d'identification en fonction de l'identité de la charge de travail.