Los agentes de IA en producción requieren acceso seguro a servicios externos. Amazon Bedrock AgentCore Identity, disponible como servicio independiente, protege la forma en que sus agentes de IA acceden a servicios externos, ya sea que se ejecuten en plataformas informáticas como Amazon ECS, Amazon EKS, AWS Lambda o en las instalaciones.
Una publicación anterior cubrió la gestión de credenciales de AgentCore Identity para agentes de IA. La ejecución de agentes en entornos informáticos como ECS plantea dos preguntas: ¿Cómo crear un punto final de enlace de sesión propiedad de la aplicación y cómo administrar el ciclo de vida del token de acceso a la carga de trabajo?
Esta publicación implementa la concesión de código de autorización (OAuth de tres patas) en Amazon ECS con enlace de sesión seguro y tokens con alcance. Esta publicación proporciona una implementación funcional con:
Enlace de sesión seguro que evita ataques CSRF y de intercambio de navegador Tokens de autenticación con alcance para cada sesión de usuario, siguiendo principios de privilegios mínimos Separación de preocupaciones entre la carga de trabajo del agente y el servicio de enlace de sesión
Autenticación y autorización con OAuth 2.0 y OIDC
Esta solución utiliza OAuth 2.0 (RFC 6749) y OpenID Connect (OIDC). OIDC autentica a los usuarios (quiénes son) y OAuth 2.0 autoriza sus acciones (qué pueden hacer).
Nos centramos en la concesión del código de autorización para el acceso delegado por el usuario. El usuario se autentica con un proveedor de identidad y otorga su consentimiento. Luego, la aplicación intercambia un código de autorización por un token de acceso, lo que crea una pista de auditoría. En este flujo, el usuario se autentica con un proveedor de identidad y otorga consentimiento para que el agente acceda a recursos específicos en su nombre. La aplicación intercambia el código de autorización resultante por un token de acceso con alcance que Amazon Bedrock AgentCore Identity protege en su bóveda de tokens. Dado que cada token está vinculado a una identidad de usuario específica con consentimiento explícito, la solución mantiene una cadena auditable desde la autenticación del usuario hasta la acción del agente.
La concesión de código de autorización es adecuada para cargas de trabajo de agente que actúan en nombre de los usuarios porque proporciona el consentimiento del usuario antes de que el agente pueda actuar, un enlace de sesión que verifica que el usuario que inició la solicitud de autorización es el mismo que otorgó el consentimiento y una delegación de alcance que limita al agente solo a los permisos que el usuario aprobó.
URL de devolución de llamada frente a URL de enlace de sesión
En este contexto, el flujo de concesión del código de autorización utiliza dos URL que a menudo se confunden:
URL de devolución de llamada: generada automáticamente al crear un cliente OAuth en AgentCore Identity. Apunta a AgentCore Identity y debe registrarse en el servidor de autorización como destino de redireccionamiento donde se envía el código de autorización después de la autenticación del usuario. URL de enlace de sesión: la URL que apunta a un servicio administrado por el cliente que completa el enlace de sesión entre el usuario autenticado y el flujo de OAuth. Este punto final es implementado y alojado por el cliente.
Descripción general de la solución
Este diagrama de arquitectura muestra cómo AgentCore Identity protege un agente de IA autohospedado en Amazon ECS. Este tutorial utiliza Microsoft Entra ID como proveedor de identidad, pero se admiten otros proveedores compatibles con OIDC. El código fuente completo y los requisitos previos para este tutorial están disponibles en el repositorio de GitHub adjunto.
La solución implementa dos servicios en Amazon ECS detrás de un balanceador de carga de aplicaciones. La carga de trabajo Agentic ejecuta el agente de IA y maneja las solicitudes de los usuarios. El servicio de enlace de sesiones procesa devoluciones de llamadas de OAuth para vincular sesiones de usuarios con tokens de acceso de terceros. Ambos servicios utilizan Amazon Bedrock AgentCore Identity para autenticar a los usuarios entrantes a través de OIDC y autorizar acciones salientes en su nombre. Las anotaciones numeradas en el diagrama corresponden a las siguientes descripciones.
Autenticación entrante y enrutamiento del tráfico: las solicitudes llegan a un balanceador de carga de aplicaciones (ALB) de Amazon, que autentica al usuario a través del flujo de autenticación OIDC integrado del ALB. El tráfico se cifra con HTTPS mediante un certificado de AWS Certificate Manager y un registro de alias A en una zona hospedada pública de Amazon Route 53 enruta el tráfico al balanceador de carga. Después de autenticar al usuario a través de OIDC, ALB reenvía la solicitud al clúster de Amazon ECS. El ALB inyecta un encabezado x-amzn-oidc-data que contiene las reclamaciones del usuario en formato JWT, con el subcampo que identifica de forma única al usuario. Carga de trabajo agente: la carga de trabajo agente expone un servidor FastAPI con un punto final /invocations que acepta un ID de sesión y un mensaje. El servidor FastAPI los pasa a un agente creado con Strands Agents. También puede utilizar LangChain u otros SDK de agente, ya que el servidor maneja las solicitudes independientemente del marco del agente. El agente llama a un modelo de lenguaje grande (LLM) en Amazon Bedrock, pero también funcionan otros proveedores de modelos. El agente almacena el estado de la sesión en un depósito de Amazon S3 y utiliza el subreclamo del usuario como prefijo clave para aislar sesiones entre usuarios. El agente también tiene herramientas para realizar acciones en nombre del usuario en GitHub, lo que requiere el token de acceso OAuth del usuario. Autenticación saliente con AgentCore Identity: cuando el agente necesita actuar en nombre del usuario en un servicio de terceros como GitHub, solicita un token de acceso OAuth a través de AgentCore Identity. Si no existe un token válido, AgentCore Identity inicia un flujo de concesión de código de autorización, solicitando al usuario que autorice el acceso. Procesamiento de devolución de llamada de OAuth: después de que el usuario autoriza el acceso, el servicio de enlace de sesión completa el flujo de OAuth vinculando la autorización a la sesión de usuario correcta a través de AgentCore Identity. Interfaz de usuario: el servidor FastAPI que aloja la carga de trabajo agente expone un punto final /docs, que representa la especificación OpenAPI como una página HTML interactiva. El usuario final interactúa con el agente a través de esta página, que proporciona una interfaz de usuario mínima para demostración.
Amazon CloudWatch captura registros y un depósito S3 dedicado almacena registros de acceso tanto para el equilibrador de carga como para el depósito de datos. ECS extrae imágenes de contenedores de Amazon ECR. Se adjunta un conjunto de reglas básicas de AWS WAF al balanceador de carga para brindar protección básica contra vulnerabilidades web comunes. Una clave administrada por el cliente (CMK) de Amazon KMS cifra los datos, excepto el depósito de registros de acceso, que requiere cifrado administrado por Amazon S3 (SSE-S3).
Identidad de Amazon Bedrock AgentCore: concesión de código de autorización
Este tutorial adapta el flujo de enlace de sesión general de AgentCore Identity para una arquitectura autohospedada que utiliza ALB para la autenticación, un servicio de enlace de sesión dedicado y llamadas API directas en lugar del SDK y el tiempo de ejecución de AgentCore.
El diagrama de secuencia muestra cómo la identidad de la carga de trabajo de AgentCore Identity, los tokens de acceso a la carga de trabajo y el proveedor de credenciales OAuth 2.0 trabajan juntos para proporcionar tokens OAuth de forma segura al agente en nombre de un usuario. Este flujo supone que el usuario autenticado aún no ha autorizado al agente a acceder a sus recursos, lo que significa que no existe ningún token válido en AgentCore Identity Token Vault.
Un usuario autenticado envía una solicitud a la carga de trabajo agente. La carga de trabajo agente extrae el ID de usuario de la subreclamación en el JWT firmado por ALB (encabezado x-amzn-oidc-data) para identificar al usuario. La carga de trabajo agente llama a la API GetWorkloadAccessTokenForUserId, pasando el ID de usuario y el nombre de carga de trabajo, para obtener un token de acceso a la carga de trabajo que representa la identidad del agente en el ámbito de este usuario. AgentCore Identity devuelve el token de acceso a la carga de trabajo a la carga de trabajo agente. La carga de trabajo agente llama a la API GetResourceOauth2Token, pasando el token de acceso a la carga de trabajo, el nombre del proveedor de credenciales OAuth 2.0 configurado, una URL de enlace de sesión (consulte el parámetro callbackUrl) y los alcances requeridos, por ejemplo, el alcance read:user de GitHub. Esto solicita un token de OAuth para el servicio de terceros (en este caso, GitHub). Debido a que no existe ningún token válido para este usuario, AgentCore Identity crea un URI de sesión que rastrea el estado del flujo de autorización en las solicitudes y respuestas posteriores durante el proceso de autenticación de OAuth 2.0. AgentCore Identity devuelve una URL de autorización y un URI de sesión a la carga de trabajo. La carga de trabajo agente devuelve la URL de autorización al usuario, solicitándole que autorice el acceso. El usuario hace clic en la URL de autorización y otorga permiso al agente en la pantalla de consentimiento del proveedor externo. El servidor de autorización envía el código de autorización a AgentCore Identity. AgentCore Identity redirige al usuario a la URL de enlace de sesión con el URI de sesión adjunto, enrutandolo al servicio de enlace de sesión. El navegador del usuario sigue la redirección al servicio de enlace de sesión a través de la URL de enlace de sesión. El ALB inyecta el JWT en el encabezado x-amzn-oidc-data. El servicio de enlace de sesión llama a la API CompleteResourceTokenAuth con el URI de sesión y el ID de usuario (extraído del JWT), vinculando la autorización completa a la sesión de usuario correcta. Si tiene éxito, devuelve una página HTML propiedad de la aplicación estática que confirma que la autorización se realizó correctamente. AgentCore Identity intercambia el código de autorización con el servidor de autorización por un token de acceso OAuth2. El servidor de autorización devuelve el token de acceso OAuth2. AgentCore Identity almacena el token en Token Vault. AgentCore Identity devuelve el éxito al servicio de enlace de sesión. El servicio de enlace de sesión muestra "Autorización completa" al usuario.
En solicitudes posteriores, si el usuario necesita volver a autorizarse depende de las credenciales que emitió el servidor de autorización. AgentCore Identity almacena tokens de acceso y tokens de actualización (cuando estén disponibles) en Token Vault. Cuando hay un token de actualización presente (como ocurre con GitHub cuando la caducidad del token de usuario a servidor está habilitada), AgentCore Identity lo utiliza automáticamente para obtener un nuevo token de acceso una vez que el original caduca, sin avisar al usuario nuevamente. Si no se emitió ningún token de actualización y el token de acceso caduca, se le pedirá al usuario que vuelva a autorizarlo. Tenga en cuenta que los tokens también se pueden revocar por parte del proveedor; en tales casos, configurar forceAuthentication: true fuerza un nuevo flujo de autenticación.
Enlace de sesión:
El enlace de sesión protege contra dos amenazas de seguridad:
Falsificación de solicitudes entre sitios (CSRF): un atacante intenta vincular su propio token OAuth a la identidad de la víctima, lo que hace que el agente de la víctima acceda sin saberlo a los recursos del atacante, lo que permite la filtración e inyección de datos.
Ataque de intercambio de navegador: un atacante engaña a la víctima para que dé su consentimiento en su nombre, vinculando el token OAuth de la víctima a la identidad del atacante, otorgándole acceso directo a los recursos de la víctima.
El enlace de sesión previene ambos ataques al garantizar que el ID de usuario en la carga de trabajo del agente coincida con el ID de usuario en el servicio de enlace de sesión, con ambas identidades verificadas criptográficamente a través de la cadena de autenticación.
AgentCore Identity también admite un parámetro customState opcional en la API GetResourceOauth2Token que se puede usar para pasar un nonce criptográficamente aleatorio para proteger su punto final de devolución de llamada contra ataques CSRF, según lo recomienda la especificación OAuth 2.0.
Por qué utilizamos GetWorkloadAccessTokenForUserId con AWS ALB y Microsoft Entra ID
La API recomendada para obtener un token de acceso a la carga de trabajo es GetWorkloadAccessTokenForJWT. Esta solución utiliza GetWorkloadAccessTokenForUserId en su lugar.
GetWorkloadAccessTokenForJWT requiere un JWT validable dinámicamente cuya firma se pueda verificar en tiempo de ejecución con las claves de firma publicadas por el emisor y cuyo reclamo de aud coincida con su aplicación. Para obtener dicho token de Microsoft Entra ID, debe incluir su ID de aplicación en el alcance de la solicitud de autorización OIDC; consulte la documentación de AgentCore Microsoft Inbound para obtener más detalles.
Sin embargo, esto es incompatible con el flujo OIDC de AWS ALB.
Como parte de su protocolo de enlace OIDC (consulte la documentación de ALB OIDC), ALB envía el token de acceso al punto final UserInfo de Entra para recuperar las reclamaciones del usuario autenticado, lo cual es un paso obligatorio en el flujo de autenticación de ALB. Este punto final de UserInfo está alojado en Microsoft Graph (https://graph.microsoft.com/oidc/userinfo) y solo acepta tokens con ámbito de Microsoft Graph. Cuando incluye su ID de aplicación en el alcance, el token de acceso resultante tiene su aplicación como audiencia, el punto final UserInfo la rechaza con un 401 y el ALB devuelve un 561.
Si elimina su ID de aplicación del alcance, Entra establece de forma predeterminada la audiencia del token de acceso en Microsoft Graph (00000003-0000-0000-c000-000000000000). El protocolo de enlace ALB se realiza correctamente, pero AgentCore no puede validar dinámicamente el JWT resultante. No se puede utilizar con GetWorkloadAccessTokenForJWT.
Esta solución: el ALB completa su protocolo de enlace utilizando el token de alcance gráfico. El ALB reenvía un JWT firmado por ALB en el encabezado x-amzn-oidc-data que contiene las reclamaciones del usuario desde el punto final UserInfo, incluida una sub reclamación que identifica de forma única al usuario autenticado. Validamos este JWT firmado por ALB utilizando las claves de firma publicadas de AWS, extraemos el sub y lo pasamos a GetWorkloadAccessTokenForUserId.
Implementación
Vea el repositorio de código completo de GitHub.
Obtención del token de acceso a la carga de trabajo
El servidor extrae el ID de usuario del subreclamo del JWT y solicita un token de acceso a la carga de trabajo de AgentCore Identity. Luego, el servidor utiliza este token, el ID de sesión y el mensaje para invocar al agente en nombre del usuario. Tenga en cuenta que el ID de sesión aquí se refiere a la sesión de conversación del agente, no al URI de la sesión OAuth del flujo de autorización.
Solicitar el token de acceso
El servidor utiliza el decorador require_access_token del SDK de AgentCore para recuperar el token de acceso de OAuth 2.0; consulte Obtener el token de acceso de OAuth 2.0. Modificamos el decorador para aceptar el token de acceso a la carga de trabajo como un parámetro explícito en lugar de resolverlo internamente, lo que brinda control directo sobre la gestión del ciclo de vida del token y al mismo tiempo preserva la lógica de recuperación de tokens y manejo de errores del SDK.
Nuestra clase de herramienta utiliza este decorador para proporcionar el token de acceso al llamar a la API de GitHub.
Cada herramienta de la clase utiliza este método, como se muestra a continuación:
Tres opciones de diseño clave:
Pydantic BaseModel como tipos de retorno: GitHubUser y GitHubProject son subclases de BaseModel. Strands deriva automáticamente descripciones de herramientas a partir de su esquema y cadenas de documentación, lo que brinda al LLM un contexto estructurado sobre el tipo de retorno de cada herramienta. Manejo de errores consistente con el tipo: cuando no existe ningún token y AgentCore Identity devuelve una URL de autorización, la devolución de llamada on_auth_url genera un AuthorizationRequiredError en lugar de devolver una cadena; una herramienta que declara GitHubUser como su tipo de retorno no puede devolver una URL. La capa de transmisión del agente detecta la excepción y muestra la URL al usuario. Alcances por herramienta: cada herramienta declara solo los alcances de OAuth que necesita, manteniendo el consentimiento alineado con el principio de privilegio mínimo.
Completar el flujo de vinculación de la sesión de OAuth
A continuación, analizamos el servicio de enlace de sesiones. Cuando un usuario autoriza el acceso en GitHub, GitHub lo redirige a {session_binding_url}?session_id={session_id}, donde session_id corresponde al URI de sesión que AgentCore Identity incluyó en la URL de autorización original. Esto vincula la solicitud de enlace de sesión con el flujo OAuth específico que inició el agente.
El servicio extrae el ID de usuario del subreclamo en el encabezado x-amzn-oidc-data, lo que garantiza una identidad coherente en todo el flujo. Luego llama a complete_resource_token_auth con el URI de sesión y el ID de usuario, lo que vincula el token de acceso resultante a la sesión de usuario correcta.
Limpieza
Para evitar incurrir en cargos futuros, elimine los recursos creados por esta solución cuando ya no sean necesarios. Siga las instrucciones para limpiar los recursos.
Conclusión
En esta publicación, aprendió cómo proteger a los agentes de IA en Amazon ECS mediante Amazon Bedrock AgentCore Identity. Vio cómo la autenticación entrante verifica la identidad del usuario a través de OIDC, cómo la autenticación saliente implementa OAuth 2.0 con enlace de sesión y cómo separar el enlace de sesión de la carga de trabajo de su agente permite un escalado independiente al tiempo que protege contra ataques. Este patrón funciona en diferentes plataformas informáticas, ya sea que ejecute agentes en ECS, EKS, Lambda o fuera de AWS por completo. También se extiende más allá de GitHub a otros servicios habilitados para OAuth 2.0 como Jira, Salesforce o Google Calendar. Próximos pasos:
Revise el código completo en GitHub para ver la implementación. Adapte el patrón a su proveedor de OAuth, reemplace GitHub con su servicio. Explore patrones adicionales en el repositorio de muestras de identidad de AgentCore. Lea la publicación sobre AgentCore Runtime para el alojamiento de agentes administrados. Sumérjase en la documentación de AgentCore Identity.
Sobre los autores
Julian Grüber es consultor de ciencia de datos en Amazon Web Services. Se asocia con clientes estratégicos para ampliar las soluciones GenAI que desbloquean el valor empresarial, trabajando tanto a nivel de caso de uso como de arquitectura empresarial. Basándose en su experiencia en matemáticas aplicadas, aprendizaje automático, negocios e infraestructura en la nube, Julian une la profundidad técnica con los resultados comerciales para abordar desafíos complejos de IA/ML.
Tobias trabaja como consultor de seguridad en Amazon Web Services como ingeniero de seguridad. Tobias combina la creación de soluciones prácticas con asesoramiento estratégico para ayudar a los clientes empresariales a acelerar su transformación en la nube y alcanzar sus objetivos comerciales. Se especializa en asociarse con clientes estratégicos para diseñar y escalar soluciones GenAI, operando tanto a nivel de caso de uso como de arquitectura empresarial.
Satveer Khurpa es arquitecto senior de soluciones especializado en WW, Amazon Bedrock AgentCore en Amazon Web Services, y se especializa en seguridad de IA agente con un enfoque en la identidad y seguridad de AgentCore. En este puesto, utiliza su experiencia en arquitecturas basadas en la nube para ayudar a los clientes a diseñar e implementar sistemas de IA agentes seguros en diversas industrias. Satveer aplica su profundo conocimiento de los patrones de IA agentes, la gestión de identidades y accesos, y los principios de seguridad de defensa en profundidad para diseñar aplicaciones basadas en agentes escalables, seguras y responsables, lo que permite a las organizaciones desbloquear nuevas oportunidades de negocio y al mismo tiempo mantener posturas de seguridad sólidas para cargas de trabajo de IA autónomas.