🔐 Decision Doc · RFC-2026-004
Migración a Autenticación JWT
con Refresh Tokens
con Refresh Tokens
Decisión técnica para reemplazar el sistema de sesiones con cookies de Django por autenticación basada en JWT, habilitando el roadmap de app móvil y API pública de NutriFlow SaaS.
1. Contexto y Motivación
Por qué tomamos esta decisión ahora
Finalizado
NutriFlow SaaS opera actualmente con un sistema de autenticación basado en sesiones Django almacenadas en PostgreSQL. Este sistema ha funcionado de forma fiable para nuestra interfaz web: 800 clínicas activas, con un SLA de 99.9% mantenido durante los últimos 14 meses.
Contexto del Roadmap
El plan de producto de 2026 incluye app móvil React Native (Q3) y API pública para integraciones con HIS/EHR (Q4). Ambos requerimientos hacen que el sistema de sesiones con cookies sea una barrera técnica, ya que las cookies de sesión no son nativas en entornos móviles ni adecuadas para autenticación stateless de APIs.
La decisión no es si migrar, sino cómo hacerlo minimizando la disrupción para las 800 clínicas en producción y garantizando el cumplimiento del RGPD y la LOPD-GDD, dado que procesamos datos de salud de pacientes (categoría especial, Art. 9 RGPD).
Este documento recoge el análisis, la decisión y el plan de implementación para que todo el equipo de ingeniería tenga el contexto completo y pueda ejecutar la migración con autonomía.
2. Alternativas Evaluadas
Opciones consideradas y razones de descarte
Finalizado
| Opción | Descripción | Decisión | Razón principal |
|---|---|---|---|
| OAuth externo (Auth0, Cognito) | Delegar autenticación a proveedor SaaS | Descartada | Dependencia de tercero para datos sanitarios; coste mensual en escala; latencia adicional; riesgo de cumplimiento RGPD por transferencia internacional |
| Mantener sesiones + proxy móvil | Añadir capa de traducción para app móvil | Descartada | Deuda técnica inaceptable: duplica la superficie de autenticación; imposible para API pública stateless; sin ventajas a largo plazo |
| PASETO tokens | Alternativa más segura a JWT estándar | Descartada | Ecosistema de librerías más reducido en Python/Django y React Native; menor familiaridad del equipo; beneficio marginal vs. JWT con RS256 |
| JWT + Refresh Tokens (RS256) | Access token de vida corta + refresh token con rotación | Seleccionada ✓ | Estándar de industria, stateless, compatible con móvil y API, equipo tiene experiencia, librerías maduras en Django y React Native |
3. La Decisión
Qué hacemos exactamente
Finalizado
Decisión Adoptada
Migrar el sistema de autenticación de NutriFlow SaaS de sesiones Django/PostgreSQL a JWT firmados con RS256, con refresh tokens rotativos y lista de revocación en Redis, manteniendo compatibilidad retroactiva durante 3 sprints mediante un período de coexistencia controlada.
Especificaciones técnicas clave:
✅ Ventajas de esta implementación
+Stateless: escala sin estado compartido en BD
+Nativo para app móvil React Native
+API pública lista desde el inicio
+RS256: firma asimétrica, no se comparte secreto
+Revocación instantánea via Redis
+Cumplimiento RGPD: datos en infraestructura propia
⚠️ Trade-offs asumidos
−Complejidad añadida: rotación de refresh tokens
−Dependencia de Redis para revocación
−Período de migración con doble sistema activo
−Gestión de par de claves RS256 (rotación anual)
−Curva de aprendizaje para 2 devs junior
Parámetros de tokens: Access token TTL: 15 minutos. Refresh token TTL: 30 días (con rotación automática en cada uso). Lista de revocación: Redis con TTL sincronizado. Algoritmo: RS256 (clave 2048-bit, rotación anual).
4. Plan de Implementación
3 sprints · 6 semanas · Disrupción mínima
Finalizado
Sprint 1 · Sem 1–2
Fundación & Backend JWT
›Generar par de claves RS256 + vault
›Endpoint /auth/token y /auth/refresh
›Middleware JWT + sesiones en paralelo
›Redis para blacklist de tokens
›Tests unitarios >90% cobertura
🗓 23 Jun – 4 Jul · Responsable: Backend team
Sprint 2 · Sem 3–4
Frontend & Migración Gradual
›Actualizar cliente web (Axios interceptors)
›SDK JWT base para React Native
›Feature flag: JWT on/off por clínica
›Migración 10% clínicas (canary)
›Monitoring: Sentry + alertas Redis
🗓 7 Jul – 18 Jul · Responsable: Full stack
Sprint 3 · Sem 5–6
Rollout Completo & Hardening
›Migración 100% clínicas
›Deprecar endpoints de sesión
›Limpiar tablas de sesión Django
›Auditoría de seguridad interna
›Documentación API para integraciones
🗓 21 Jul – 1 Ago · Responsable: DevOps + Sec
Criterio de Rollback
Si en Sprint 2 el error rate de autenticación supera el 0.5% en el segmento canary durante más de 15 minutos, se activa rollback automático al sistema de sesiones mediante feature flag. El sistema dual garantiza reversión sin downtime.
5. Riesgos y Mitigaciones
Incluyendo gap detectado en Reader Testing
Finalizado · 1 gap corregido
Gap detectado por Reader Testing
El lector simulado (Claude sin contexto) preguntó: "¿Cómo se revocan tokens si hay una brecha de seguridad?" — la sección original no respondía con claridad. Corrección aplicada: protocolo de revocación de emergencia ahora explícito en R-02.
R-01 · Tokens de larga vida comprometidos durante migración
ALTO
Mitigación
Access tokens de 15 min limitan la ventana de exposición. Refresh tokens en Redis permiten revocación inmediata. Rotación automática en cada uso detecta reutilización.
R-02 · Brecha de seguridad: protocolo de revocación masiva
ALTO
Protocolo de emergencia (corregido tras Reader Test)
En caso de brecha: (1) incrementar versión de clave en Redis → invalida TODOS los refresh tokens, (2) rotar par de claves RS256 → invalida todos los access tokens activos en <15 min, (3) notificación a clínicas por email automatizado.
R-03 · Downtime de Redis afecta autenticación
MEDIO
Mitigación
Redis con replica + sentinel. Fallback: aceptar tokens válidos sin check de blacklist durante máx. 5 min (ventana de riesgo tolerable). Alertas PagerDuty si Redis latency >100ms.
R-04 · Clínicas con sesiones largas afectadas en cutover
MEDIO
Mitigación
Email proactivo 48h antes del cutover de cada clínica. Ventana de coexistencia de 2 semanas (sprint 2). Soporte prioritario durante las primeras 72h post-migración.
R-05 · Curva de aprendizaje equipo junior
BAJO
Mitigación
Workshop interno de 4h sobre JWT antes del Sprint 1. Pair programming con dev senior en los primeros endpoints. Code review obligatorio en toda la capa de autenticación.
R-06 · Cumplimiento RGPD / LOPD-GDD
BAJO
Mitigación
JWT no contiene datos de salud (solo user_id + clinic_id + roles). Todo procesamiento en infraestructura propia (sin terceros). Revisión DPO antes del sprint 3. Registro en el ROT actualizado.
Aprobaciones y Criterios de Éxito
Aprobado
Criterios de éxito para dar la migración por completada:
- 100% de clínicas migrando a JWT sin incidencias P0
- Error rate de autenticación <0.1% en las 72h post-cutover completo
- SDK móvil JWT funcionando en build de prueba de React Native
- Auditoría de seguridad interna aprobada (Sprint 3)
- Documentación API pública publicada en developer.nutriflow.io
- Tablas de sesión Django eliminadas de PostgreSQL
CTO · Decisión Final
Marta Solís
✅ Aprobado · 16 Jun 2026
Tech Lead Backend
Carlos Ramos
✅ Revisado · 15 Jun 2026
DPO / Compliance
Ana Torres
⏳ Pendiente · Sprint 3
Trazabilidad del Workflow — Coautoría de Documentación Estructurada (CULTIVA IA)
✓
Etapa 1
Context Gathering
18 preguntas de clarificación · Info dump de contexto técnico + regulatorio · Audiencia y objetivo definidos
✓
Etapa 2 · §1
Contexto y Motivación
Brainstorm 8 puntos → curación → 2 iteraciones → sección final
✓
Etapa 2 · §2–3
Alternativas + Decisión
4 opciones evaluadas · pros/cons · parámetros técnicos definidos
✓
Etapa 2 · §4–5
Plan + Riesgos
3 sprints timeline · 6 riesgos identificados · criterios rollback
✓
Etapa 3
Reader Testing
7 preguntas lector · 1 gap → §Riesgos corregida · re-test aprobado