ADR-001: Propagacion de JWT entre Microservicios
Estado: Aceptada
Fecha: 2026-05-18
Autor: Equipo de Arquitectura
Contexto
La plataforma necesita propagar la identidad del usuario de forma segura entre microservicios. Cuando un servicio recibe una solicitud autenticada y necesita invocar a otro servicio interno, debe transmitir la identidad del usuario original (tenant, roles, permisos) de manera confiable.
Se evaluaron dos enfoques principales:
- Headers personalizados (
X-Tenant-Id,X-User-Id): el API Gateway termina el JWT y propaga la identidad como headers internos. - Propagacion del JWT completo: cada servicio recibe y valida el token original.
Decision
Propagar el JWT completo entre servicios. Cada microservicio valida el token de forma independiente usando JWKS (JSON Web Key Set) del proveedor de identidad.
El Gateway realiza una validacion inicial (firma, expiracion) pero no termina el token. Los servicios internos re-validan para garantizar integridad end-to-end.
Alternativas Consideradas
| Alternativa | Pros | Contras |
|---|---|---|
| Headers personalizados (enfoque actual IdFlow) | Simple, menor latencia por servicio | Punto unico de confianza en el Gateway, vulnerable a spoofing interno |
| API Gateway termina JWT e inyecta headers | Servicios internos mas simples | Si el Gateway se compromete, toda la cadena queda expuesta |
| JWT propagado (elegida) | Cada servicio valida, sin punto unico de compromiso | Requiere cache JWKS en cada servicio, ligeramente mas latencia |
Consecuencias
Positivas
- Cada servicio valida la identidad de forma independiente, eliminando puntos unicos de compromiso
- Funciona naturalmente para llamadas service-to-service sin infraestructura adicional
- El token es inmutable y firmado criptograficamente, imposible de falsificar internamente
- Compatible con zero-trust architecture
Negativas
- Cada servicio necesita mantener un cache de JWKS
- Ligeramente mas latencia por la validacion en cada hop (mitigado con cache)
- Los tokens tienen un tamano mayor que headers simples
Riesgos
- Si el TTL del cache JWKS es muy largo, una rotacion de claves podria causar rechazos temporales
- Tokens con muchos claims pueden exceder limites de tamano de headers en algunos proxies