View a markdown version of this page

Obtenga el token de acceso a la carga de - Amazon Bedrock AgentCore
¿Qué es un token de acceso a la carga de trabajo?Cómo obtienen los tokens automáticamente Runtime y Gateway¿Cómo recuperar manualmente los tokens de acceso a las cargas de trabajo?Controles de seguridad para la GetWorkloadAccessTokenForUserIdAPI

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 que conlleva trabajar con ellos es fundamental para crear aplicaciones de agente 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 y 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 las cargas de trabajo a las instancias de ejecución de los agentes como encabezados de carga útil, lo que elimina la necesidad de gestionar manualmente los tokens en la mayoría de los escenarios.

Características clave

  • First-party solo servicios: los tokens de acceso a las cargas de trabajo sirven 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 impide su extracción o uso indebido

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

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

Cuando se invoca un agente mediante 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 el emisor y las subafirmaciones del token de OAuth que representan la identidad del usuario

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

  4. Runtime invoca GetWorkloadAccessTokenForJWT con la identidad del usuario y 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 la carga útil de 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 las cargas de trabajo?

Existen 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 el agente que llama tiene un JWT emitido por un proveedor de identidad para el usuario final, solicite un token de acceso a la carga de trabajo utilizando. GetWorkloadAccessTokenForJWT Al proporcionar un JWT, AgentCore Identity valida el token para asegurarse de que está correctamente firmado y no ha caducado, y utiliza las menciones «is» y «sub» para identificar al usuario de forma exclusiva. Las credenciales almacenadas por el agente en nombre del usuario están asociadas a esta identidad verificada criptográficamente, y las recuperaciones futuras requieren un token de acceso a la carga de trabajo válido que lleve la misma identidad.

Utilice este patrón cuando:

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

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

  • Va a realizar la implementación en producción

Patrón 2: UserId-based identificación

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

Utilice este patrón cuando:

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

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

  • La arquitectura empresarial resuelve la identidad del usuario desde el principio y transfiere un identificador de confianza a la carga de trabajo del agente

Compensación: la plataforma trata el USERID como una cadena opaca y no puede verificarlo con una identidad de usuario final autenticada. El enlace de seguridad se basa en que la carga de trabajo de llamadas transmita el USeriD correcto y en que las políticas de IAM tengan el alcance adecuado. Consulte para ver los controles recomendadosControles de seguridad para la GetWorkloadAccessTokenForUserIdAPI.

Ejemplos de código

Los siguientes ejemplos ilustran el uso del AgentCore SDK para recuperar un token de acceso a una 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 GetWorkloadAccessTokenForUserIdAPI

La GetWorkloadAccessTokenForUserId API acepta una cadena de identificador de usuario proporcionada por la persona que llama y emite un token de acceso a la carga de trabajo destinado a ese par de usuario-agente. Esta API está diseñada para ayudar a los clientes empresariales que necesitan pasar cadenas de ID de usuario administradas por el cliente y a los creadores 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 una identidad de usuario final autenticada. El enlace de seguridad depende completamente de que la carga de trabajo de llamadas transmita el USERID correcto y de que sus políticas de IAM tengan el alcance adecuado. Si su aplicación tiene acceso a un JWT que identifique al usuario final, utilícelo GetWorkloadAccessTokenForJWT en su lugar, ya que valida el emisor, la firma y el vencimiento 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: además, Runtime-managed las identidades Gateway-managed de la carga de trabajo no pueden recuperar los tokens directamente. Esto evita que los agentes extraigan los tokens para utilizarlos indebidamente

  • Requisitos de permiso de IAM: las personas que llamen deben tener los permisos de IAM adecuados, incluidos, 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 los ID de usuario para varios proveedores de identidad: cuando utilice varios proveedores de identidad, divida los ID de usuario según el patrón provider_id+user_id para evitar colisiones de usuarios entre distintos proveedores. Por ejemplo, utilice cognito+user123 y distinga auth0+user123 a los usuarios con el mismo identificador en distintos proveedores de identidad

Controles de seguridad recomendados

Como la plataforma no puede verificar la cadena de ID de usuario, eres responsable de garantizar la integridad del valor que se pasa a esta API. Aplica los siguientes controles:

  • Prefiere GetWorkloadAccessTokenForJWT cuando haya 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.

  • Obtenga 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 la sesión o una capa de resolución de identidad ascendente) en lugar de aceptar valores arbitrarios proporcionados por el cliente. Esto evita que una persona autenticada se haga pasar por otro usuario.

  • Restrinja el permiso de IAM: solo las personas de confianza deben tener el permiso. bedrock-agentcore:GetWorkloadAccessTokenForUserId Limite este permiso a recursos de identidad de cargas de trabajo específicos. No lo concedas de forma generalizada mediante políticas gestionadas o declaraciones de recursos comodín.

  • Denegar GetWorkloadAccessTokenForUserId cuando no sea necesario: en el caso de las cargas de trabajo que siempre tienen un JWT disponible, deniegue explícitamente la acción en las políticas de IAM para evitar que se utilice la ruta de UserID:

    {
   "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 UserID que se transfiere. Se utiliza AWS CloudTrail para supervisar GetWorkloadAccessTokenForUserId las llamadas y detectar valores de UserID 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 Limitar el acceso a los proveedores de credenciales por identidad de carga de trabajo.