View a markdown version of this page

Obtenga el token de acceso a la carga de - Base amazónica AgentCore
¿Qué es un token de acceso a la carga de trabajo?Cómo Runtime y Gateway obtienen automáticamente los tokensCómo recuperar manualmente los tokens de acceso a la carga de trabajoControles de seguridad para la API GetWorkloadAccessTokenForUserId

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Obtenga el token de acceso a la carga de

Comprender qué son los tokens de acceso a la carga de trabajo, cómo obtenerlos y los aspectos de seguridad relacionados con el trabajo con ellos es fundamental para crear aplicaciones de agentes seguras. En esta sección se describen los conceptos clave y los patrones de implementación que necesita conocer.

¿Qué es un token de acceso a la carga de trabajo?

Un token de acceso a la carga de trabajo es un token de acceso opaco AWS firmado que permite a los agentes acceder a AgentCore servicios propios, como los proveedores de credenciales salientes. Runtime entrega automáticamente los tokens de acceso a la carga de trabajo a las instancias de ejecución de los agentes en forma de encabezados de carga útil, lo que elimina la necesidad de administrar manualmente los tokens en la mayoría de los casos.

Características clave

  • First-party Solo servicios: los tokens de acceso a la carga de trabajo se utilizan exclusivamente para acceder AWS a AgentCore servicios propios y no se pueden usar para servicios externos

  • Entrega automática: Runtime y Gateway proporcionan automáticamente estos tokens a los agentes durante la ejecución

  • Seguridad desde el diseño: las identidades de los Runtime-managed agentes no pueden recuperar directamente los tokens de acceso a la carga de trabajo, lo que evita su extracción y uso indebido

  • Vinculación de la identidad del usuario y del agente: los tokens contienen información sobre la identidad del usuario y la identidad del agente para garantizar un acceso seguro a las credenciales

Cómo Runtime y Gateway obtienen automáticamente los tokens

Cuando se invoca a un agente a través de AgentCore Runtime o Gateway con autenticación entrante, el servicio gestiona automáticamente la generación de los tokens de acceso a la carga de trabajo:

  1. Runtime valida el token OAuth del proveedor de identidad entrante (emisor, firma)

  2. Runtime extrae las notificaciones del emisor y las subnotificaciones del token de OAuth que representa la identidad del usuario

  3. Runtime obtiene la identidad de carga de trabajo asociada del agente

  4. Runtime invoca tanto GetWorkloadAccessTokenForJWT con la identidad del usuario como con la identidad de la carga de trabajo del agente

  5. Runtime transfiere el token de acceso a la carga de trabajo al código del agente como parte del encabezado de carga útil de la invocación

Este proceso automático garantiza que los agentes reciban los tokens con el alcance adecuado sin intervención manual.

Cómo recuperar manualmente los tokens de acceso a la carga de trabajo

Hay dos patrones que se pueden utilizar para recuperar el token de acceso a la carga de trabajo, en función de cómo se pueda identificar al usuario final del agente:

Patrón 1: JWT-based identificación (recomendado para la producción)

Si la persona que llama al agente tiene un JWT emitido por un proveedor de identidad para el usuario final, solicita un token de acceso a la carga de trabajo mediante. GetWorkloadAccessTokenForJWT Cuando proporcionas un JWT, AgentCore Identity valida el token para garantizar que esté correctamente firmado y que no haya caducado, y utiliza sus afirmaciones «iss» y «sub» para identificar de forma exclusiva al usuario. Las credenciales almacenadas por el agente en nombre del usuario se asocian a esta identidad verificada criptográficamente, y las recuperaciones futuras requieren un token de acceso a la carga de trabajo válido con la misma identidad.

Utilice este patrón cuando:

  • Tu aplicación se integra con un proveedor de identidad (Cognito, Auth0, Okta, etc.)

  • Necesitas una prueba criptográfica de la identidad del usuario final

  • Está realizando la implementación en producción

Patrón 2: UserId-based identificación

Si la persona que llama del agente no tiene un JWT que identifique al usuario final, solicite un token de acceso a la carga de trabajo GetWorkloadAccessTokenForUserId con una cadena única que identifique al usuario.

Usa este patrón cuando:

  • Tu aplicación administra sus propios identificadores de usuario y necesitas pasar las cadenas de ID de usuario administradas por el cliente a Identity AgentCore

  • Estás en un escenario de desarrollo o inicio rápido en el que un token de IdP aún no está disponible

  • La arquitectura de su empresa resuelve la identidad de los usuarios de forma ascendente y transfiere un identificador confiable a la carga de trabajo del agente

Compensación: la plataforma trata el identificador de usuario como una cadena opaca y no puede compararlo con la identidad de un usuario final autenticado. El enlace de seguridad depende de que la carga de trabajo de la llamada indique el ID de usuario correcto y de que las políticas de IAM se definan adecuadamente. Consulte para ver los controles recomendadosControles de seguridad para la API GetWorkloadAccessTokenForUserId.

Ejemplos de código

Los siguientes ejemplos ilustran el uso del AgentCore SDK para recuperar un token de acceso a la carga de trabajo mediante estos dos métodos:

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”)

Controles de seguridad para la API GetWorkloadAccessTokenForUserId

La GetWorkloadAccessTokenForUserId API acepta una cadena de identificación de usuario proporcionada por la persona que llama y emite un token de acceso a la carga de trabajo destinado a ese par usuario-agente. Esta API está diseñada para ayudar a los clientes empresariales que necesitan transferir cadenas de ID de usuario administradas por los clientes y a los desarrolladores que no tienen tokens de proveedor de identidad (IdP) disponibles durante el desarrollo.

importante

Cuando la usasGetWorkloadAccessTokenForUserId, la plataforma trata el userId valor como una cadena opaca y no lo compara con la identidad de un usuario final autenticado. El enlace de seguridad depende exclusivamente de que la carga de trabajo de la llamada indique el ID de usuario correcto y de que tus políticas de IAM se definan adecuadamente. Si tu aplicación tiene acceso a un JWT que identifique al usuario final, utilízalo GetWorkloadAccessTokenForJWT en su lugar, que valida el emisor, la firma y la caducidad del token antes de emitir un token de acceso a la carga de trabajo.

La GetWorkloadAccessTokenForUserId API implementa varios controles de seguridad para evitar el acceso no autorizado:

  • Validación de la identidad de la carga de trabajo: la API verifica que la identidad solicitante tenga permiso para actuar en nombre de la identidad de la carga de trabajo especificada

  • Service-managed restricción de identidad: Runtime-managed y las identidades Gateway-managed de carga de trabajo no pueden recuperar los tokens directamente. Esto evita que los agentes extraigan los tokens para utilizarlos indebidamente

  • Requisitos de permisos de IAM: las personas que llamen deben tener los permisos de IAM adecuados, que incluyen, y GetWorkloadAccessToken GetWorkloadAccessTokenForUserId GetWorkloadAccessTokenForJWT

  • Alcance de los tokens: los tokens se asignan al par usuario-agente específico, lo que garantiza que otro no pueda acceder a las credenciales almacenadas en un usuario

  • Partición de ID de usuario para varios proveedores de identidad: cuando utilices varios proveedores de identidad, divide tus ID de usuario según el patrón provider_id+user_id para evitar colisiones de usuarios entre diferentes proveedores. Por ejemplo, usa cognito+user123 y distingue auth0+user123 a los usuarios con el mismo identificador en diferentes proveedores de identidad

Controles de seguridad recomendados

Como la plataforma no puede verificar la cadena de ID de usuario, usted es responsable de garantizar la integridad del valor transferido a esta API. Aplica los siguientes controles:

  • Prefiere GetWorkloadAccessTokenForJWT cuando hay un JWT disponible: la JWT-based ruta valida el emisor y la firma del token, lo que proporciona una prueba criptográfica de la identidad del usuario. Úselo GetWorkloadAccessTokenForUserId solo cuando un JWT no esté disponible.

  • Derive el ID de usuario de una fuente confiable: el valor del ID de usuario debe derivarse del contexto del principal autenticado (por ejemplo, la identidad de la persona que llama de IAM, los atributos de sesión o una capa de resolución de identidad ascendente), en lugar de aceptar valores arbitrarios proporcionados por el cliente. De este modo, se evita que una persona autenticada se haga pasar por otro usuario.

  • Restrinja el permiso de IAM: solo los directores de confianza deben tener el permiso. bedrock-agentcore:GetWorkloadAccessTokenForUserId Amplíe este permiso a recursos de identidad de cargas de trabajo específicos. No lo conceda de manera generalizada mediante políticas administradas o declaraciones de recursos comodín.

  • GetWorkloadAccessTokenForUserIdRechaza cuando no sea necesario: en el caso de las cargas de trabajo que siempre tienen un JWT disponible, deniega explícitamente la acción en las políticas de IAM para evitar que se utilice la ruta del identificador de usuario:

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

  • Implemente el registro de auditoría: registre la relación entre el principal de IAM autenticado y el valor de ID de usuario que se está transfiriendo. Utilícelo AWS CloudTrail para supervisar las GetWorkloadAccessTokenForUserId llamadas y detectar valores de ID de usuario inesperados.

Si aparece el error «WorkloadIdentity está vinculado a un servicio y la persona que llama no puede recuperar un token de acceso», esto indica que Runtime o Gateway administran la identidad de la carga de trabajo y no pueden recuperar los tokens directamente. Esta restricción ayuda a mantener los límites de seguridad y evita el acceso no autorizado a los tokens.

Para obtener controles de seguridad adicionales, puede implementar políticas de acceso detalladas para restringir qué identidades de carga de trabajo pueden acceder a proveedores de credenciales específicos. Para obtener más información, consulte Disminuir el acceso a los proveedores de credenciales por identidad de carga de trabajo.