Lambda authorizers: seguridad, JWT y caché en API Gateway

Por

Publicado el

Actualizado el

Revisado el

Si tu API necesita reglas de autenticación propias, un Lambda authorizer puede decidir qué solicitudes pasan a API Gateway. Para aceptar JWT estándar en una HTTP API, empieza por evaluar el authorizer JWT integrado: API Gateway valida la firma y los claims configurados sin invocar una función Lambda en cada solicitud. Usa Lambda cuando necesites lógica que esa opción no cubre. En ambos casos, el tipo de API, el formato de respuesta y el caché determinan qué significa una autorización válida.

Primero identifica el tipo de API

API Gateway REST y HTTP no comparten un único formato de authorizer:

API Opciones de authorizer Respuesta que espera API Gateway
REST API Lambda TOKEN recibe un token de una cabecera; REQUEST recibe parámetros de la solicitud y variables de contexto. Una política IAM con principalId y policyDocument.
HTTP API Un authorizer JWT integrado valida JWT de un proveedor OIDC/OAuth. Si hace falta Lambda, el tipo es REQUEST; se configura el formato de payload 1.0 o 2.0. 1.0 devuelve una política IAM. 2.0 admite una política o una respuesta simple { "isAuthorized": true/false } si habilitas esa opción.

El authorizer JWT integrado es una función de HTTP API, no un Lambda authorizer. Si lo eliges, configura un proveedor de identidad, issuer y audience reales. API Gateway comprueba la firma con las claves publicadas por el issuer y valida iss, aud (o client_id si no hay aud), exp y, cuando aparecen, nbf e iat. También puede exigir scopes en una ruta. AWS advierte que no existe una forma estándar de distinguir un access token de un ID token: exige scopes o un issuer/audience que identifique los tokens de acceso de tu proveedor. Referencia: authorizers JWT para HTTP API.

Por ejemplo, este comando crea un authorizer JWT para una HTTP API. Sustituye el issuer, el audience, el ID de API y el scope por los valores emitidos y configurados en tu entorno:

aws apigatewayv2 create-authorizer \
  --api-id "$API_ID" \
  --name orders-jwt \
  --authorizer-type JWT \
  --identity-source '$request.header.Authorization' \
  --jwt-configuration 'Audience=orders-app,Issuer=https://issuer.example'

Este ejemplo presupone una HTTP API y una ruta ya creadas, AWS CLI configurada con permisos para modificar esa API y los valores reales de tu proveedor de identidad. API_ID identifica el API; el resultado de create-authorizer devuelve el AUTHORIZER_ID. Asígnalo a una ruta existente; añade un scope solo si el token y la ruta usan ese permiso:

aws apigatewayv2 update-route \
  --api-id "$API_ID" \
  --route-id "$ROUTE_ID" \
  --authorization-type JWT \
  --authorizer-id "$AUTHORIZER_ID" \
  --authorization-scopes orders/read

Si la etapa tiene AutoDeploy desactivado, publica el cambio creando un deployment para esa etapa:

aws apigatewayv2 create-deployment \
  --api-id "$API_ID" \
  --stage-name "$STAGE"

La documentación de AWS detalla cómo crear el authorizer y asociarlo a una ruta, y cómo se despliegan los cambios de una HTTP API. El authorizer JWT integrado admite algoritmos RSA; API Gateway puede conservar una clave pública en caché hasta dos horas, así que durante una rotación mantén un período en que las claves anterior y nueva sigan siendo válidas.

Cinco controles que sí cambian el resultado

1. Valida identidad y permisos, no solo la forma del token

Un JWT decodificado no es un JWT verificado. Si implementas la validación dentro de Lambda, usa una biblioteca mantenida y verifica la firma con claves confiables del proveedor. Comprueba issuer, audience y expiración; valida scopes o permisos requeridos para la ruta. No aceptes un algoritmo o una clave elegidos por datos no confiables del propio token.

Prefiere el authorizer JWT de HTTP API cuando cubra el flujo de identidad. Si REST API o una regla propia requiere Lambda, implementa únicamente la validación que falte y prueba rechazos, expiración, claims incorrectos y rotación de claves. Envía tokens portadores en la cabecera Authorization, no en la URL: además de exponerlos en registros o historiales, un JWT largo en la ruta puede superar límites de longitud de los ARN usados en políticas de REST API. Formato de respuesta y límites de authorizers REST.

2. Separa el permiso para invocar de los permisos de la función

Hay dos decisiones IAM distintas:

No confundas el rol de ejecución con el permiso de invocación. AWSLambdaBasicExecutionRole da a la función los permisos básicos para escribir logs en CloudWatch; su política no concede lectura de secretos ni acceso a datos. Tampoco añadas permisos amplios de Secrets Manager para guardar un token estático compartido: eso crea otra credencial que distribuir y proteger. AWS explica cómo otorgar acceso a una función mediante políticas basadas en recursos.

3. Haz que la política y la clave de caché describan el mismo alcance

En una REST API, TOKEN usa como clave el token de la cabecera configurada. REQUEST puede combinar fuentes de identidad —por ejemplo, la cabecera y variables de contexto como método y ruta—; si el caché está activo, todas deben estar presentes y participan en la clave. La función devuelve una política IAM con principalId y recursos execute-api:Invoke permitidos.

En una HTTP API con Lambda, las fuentes de identidad también forman la clave. Una respuesta simple isAuthorized: true almacenada se aplica a todas las rutas que comparten esos valores. Si los permisos cambian por ruta, añade $context.routeKey como fuente de identidad o devuelve una política IAM que limite los recursos. En REST, la política almacenada también debe cubrir solo los métodos y recursos que el mismo conjunto de identidad puede usar; una política demasiado estrecha puede permitir la primera solicitud y causar 403 en otra ruta durante el TTL. AWS describe las fuentes de identidad y el caché de HTTP API y las políticas de salida de REST API.

No hay un TTL universalmente seguro. REST API usa 300 segundos si no se configura otro valor y permite hasta 3600; HTTP API Lambda permite authorizerResultTtlInSeconds de 0 a 3600. Un TTL de cero desactiva el caché. Elige el valor según cuánto tiempo puede seguir vigente una decisión después de que cambien los permisos: API Gateway no vuelve a ejecutar el authorizer mientras usa el resultado almacenado, de modo que una autorización en caché puede sobrevivir a una revocación o a la expiración del token hasta que venza ese resultado. Si necesitas comprobar revocaciones en cada solicitud, desactiva el caché.

Para una intervención operativa, AWS permite vaciar todas las entradas de authorizer de una etapa. Hazlo con cuidado: invalida decisiones de todos los clientes de esa etapa y puede aumentar las invocaciones a Lambda. No equivale a revocar un único token.

# REST API
aws apigateway flush-stage-authorizers-cache \
  --rest-api-id "$REST_API_ID" \
  --stage-name "$STAGE"

# HTTP API con Lambda authorizer
aws apigatewayv2 reset-authorizers-cache \
  --api-id "$HTTP_API_ID" \
  --stage-name "$STAGE"

Cache-Control: max-age=0 se refiere a invalidar una entrada de la caché de respuestas de integración de REST API cuando el cliente tiene permiso. No es un bypass ni una invalidación del resultado de un Lambda authorizer. AWS documenta por separado el vaciado del caché de authorizers REST, el reinicio del caché de authorizers HTTP y la caché de respuestas de API.

4. Distingue credenciales inválidas de fallos del authorizer

Respuesta REST API con Lambda authorizer HTTP API con Lambda authorizer
401 Unauthorized Una fuente REQUEST requerida pero ausente devuelve 401 antes de invocar Lambda cuando el caché está activo. Para TOKEN, el authorizer puede devolver la respuesta/error especial Unauthorized para el caso no autenticado. Una fuente de identidad configurada pero ausente devuelve 401 sin invocar Lambda. AWS también documenta la respuesta {"errorMessage":"Unauthorized"} para devolver 401 si no configuras identity sources.
403 Forbidden Una política IAM Deny o que no concede el método y recurso solicitados rechaza la llamada. Una política IAM Deny o una respuesta simple isAuthorized: false deniega la ruta; el resultado cacheado puede denegar otras rutas que compartan identidad.
500 Internal Server Error Un error del authorizer que no sea la respuesta especial Unauthorized, un fallo de invocación o una salida inválida indica que la autorización no pudo completarse. API Gateway no puede invocar Lambda, la función falla o devuelve un formato inválido.

En una REST API, el authorizer devuelve una política y principalId. En HTTP API Lambda, el payload 1.0 devuelve política; 2.0 devuelve política o respuesta simple. No mezcles una respuesta simple con un authorizer o payload que espera política IAM. Un 401 o 403 puede tener otras causas de configuración en la API, así que usa los logs para confirmar el origen. AWS documenta los formatos HTTP, identity sources y errores de invocación.

5. Registra la decisión sin registrar la credencial

Activa access logs de API Gateway y los logs necesarios de Lambda en CloudWatch. Registra el ID de solicitud, ruta, resultado (permitir, denegar o error), latencia y un identificador de principal que no sea un secreto. No registres la cabecera Authorization, el JWT, secretos, el evento completo ni claims personales que no necesites. Un token escrito en un log puede seguir sirviendo como credencial mientras sea válido.

Para investigar fallos, REST API dispone de variables específicas como $context.authorizer.error, $context.authorizer.status y $context.authorizer.latency. HTTP API ofrece $context.authorizer.error, $context.requestId, $context.status y $context.responseLatency; mide la duración de la función con métricas o logs de Lambda. Inclúyelas solo en un formato de logs controlado y evita guardar campos sensibles de la solicitud. Variables de logging para REST y para HTTP API.

Preguntas frecuentes

¿300 segundos es el TTL recomendado?

No. En REST API es el valor predeterminado cuando no se especifica otro, no una recomendación para todas las aplicaciones. Ajusta el TTL a la ventana de revocación tolerable y al tiempo de vida de las credenciales. Usa cero si cada solicitud debe volver a consultar el estado de autorización.

¿Puedo invalidar un solo resultado del caché de authorizers?

Los comandos documentados para REST y HTTP vacían todas las entradas de la etapa indicada. Si necesitas revocación inmediata de una identidad sin afectar a otras, no dependas de una entrada cacheada: desactiva el caché o diseña la autorización para comprobar el estado actualizado en cada solicitud.

¿Qué contenido conviene pasar en context?

Solo datos mínimos y no secretos que la integración necesite, como un identificador interno de principal o tenant y permisos ya calculados. El contexto puede llegar a la integración y a los logs; no lo uses para devolver tokens ni credenciales.

Sigue aprendiendo y participa

Si recién estás aprendiendo AWS, esta guía inicial de AWS repasa IAM, MFA y credenciales temporales antes de entrar a los authorizers. Como complemento práctico, el repositorio aws-iam-security-lab describe un ejercicio con MFA y una política acotada a un bucket de S3; practica IAM general, no implementa ni prueba Lambda authorizers.

Para conversar sobre controles de acceso y seguridad en AWS, el AWS Security Users Group LatAm conecta a personas hispanohablantes, y el canal regional @AWSSecurityLATAM publica grabaciones sobre seguridad, respuesta a incidentes y cumplimiento.

La comunidad AWS Women Colombia comparte charlas técnicas en español; puedes explorar su archivo de eventos y grabaciones y su canal de YouTube, que incluye sesiones de seguridad.

Eventos anunciados al 4 de octubre de 2026

Las agendas y condiciones pueden cambiar. Consulta la ficha del organizador y la Agenda de próximos eventos AWS para ver qué sigue después de esas fechas; también puedes encontrar un grupo por país en el directorio de comunidades o canales técnicos en el directorio de creadores.