ADR 005: WorkOS AuthKit para autenticacion

Estado: Aceptado Fecha: 2025-03-15

Contexto

Necesitamos autenticacion para una plataforma SaaS multi-tenant con requisitos de SSO empresarial. La solucion debe funcionar con Cloudflare Workers (runtime edge, sin APIs de Node.js), soportar SPAs React y gestionar multi-tenancy basado en organizaciones.

Decision

Usar WorkOS AuthKit con su flujo OAuth hosted y el React SDK (@workos-inc/authkit-react@^1.3.0).

Consecuencias

Positivas

• SSO empresarial listo para usar (SAML, OIDC) -- critico para clientes B2B
• Multi-tenancy basado en organizaciones nativo en WorkOS
• Tier gratuito generoso: 1M de usuarios activos mensuales
• React SDK (@workos-inc/authkit-react@^1.3.0) con AuthKitProvider, hook useAuth
• Tokens basados en JWT: validacion en edge con la libreria jose@^6.1.3 (sin necesidad de Node.js crypto)
• Directory sync para aprovisionamiento de usuarios (SCIM)
• UI de login hosted (AuthKit) -- no es necesario construir flujos de login/registro/reseteo de contrasena
• RBAC con roles y permisos

Negativas

• Dependencia de terceros para infraestructura critica de autenticacion
• Menos personalizable que construir la autenticacion desde cero
• La UI hosted de AuthKit tiene opciones de personalizacion visual limitadas
• Vendor lock-in: cambiar de proveedor de autenticacion requiere una migracion significativa
• El SDK de WorkOS no tiene un paquete nativo para Cloudflare Workers (la validacion JWT se hace manualmente con jose@^6.1.3)

Estrategia de fallback (indisponibilidad de WorkOS)

Si WorkOS no esta disponible temporalmente (caida, problemas de red, rate limiting), aplica el siguiente comportamiento de fallback:

Las sesiones cacheadas continuan

• Las sesiones autenticadas existentes dependen de JWTs validados localmente usando jose@^6.1.3. La validacion de tokens se realiza completamente en edge usando el JWKS (JSON Web Key Set) cacheado y no requiere un round-trip a WorkOS.
• Las sesiones permanecen validas hasta que el JWT expira (basado en el claim exp). Los usuarios con tokens activos y no expirados no experimentan interrupcion.
• La respuesta del endpoint JWKS se cachea con un TTL (recomendado: 1 hora). Si WorkOS esta caido pero el JWKS cacheado no ha expirado, la validacion de tokens sigue funcionando para todos los usuarios, incluidos los que realizan nuevas peticiones.

Los nuevos logins fallan con gracia

• Los nuevos intentos de login que requieren el flujo OAuth hosted de WorkOS fallaran, ya que la redireccion de AuthKit depende de la disponibilidad de WorkOS.
• La aplicacion debe presentar una pagina de error amigable explicando que el login no esta disponible temporalmente. Evitar exponer respuestas de error sin procesar.
• Se debe proporcionar una accion clara de "Reintentar" para que los usuarios puedan volver a intentarlo sin navegar fuera de la pagina.

Reintento con backoff exponencial

• Todas las llamadas API a WorkOS (intercambio de tokens, info de usuario, consultas de organizacion) deben implementar logica de reintento con backoff exponencial.
• Programa de reintentos recomendado: delay inicial 1s, factor de backoff 2x, maximo 5 reintentos, delay maximo 30s. Agregar jitter (aleatorizado +/- 20%) para evitar thundering herd.
• Tras agotar los reintentos, fail open para operaciones de lectura (servir datos cacheados) y fail closed para operaciones de escritura (denegar la accion y notificar al usuario).
• Patron circuit breaker: tras un numero configurable de fallos consecutivos (p.ej., 10), dejar de llamar a WorkOS durante un periodo de cooldown (p.ej., 60s) antes de probar de nuevo. Esto protege contra fallos en cascada.

Monitorizacion y alertas

• Los health checks contra los endpoints de la API de WorkOS deben ejecutarse periodicamente. Alertar al equipo de guardia si WorkOS no es alcanzable durante mas de 5 minutos.
• Registrar todos los fallos de la API de WorkOS con correlation IDs para analisis post-incidente.

Alternativas consideradas

Auth0

Maduro y rico en funcionalidades pero caro a escala (el precio por MAU aumenta de forma pronunciada). El SSO empresarial es un complemento con coste significativo. Setup mas complejo que WorkOS para casos de uso B2B.

Clerk

Excelente DX e integracion con React, componentes de UI preconstruidos atractivos. Pero: menor foco en SSO empresarial, sin SCIM/directory sync, mayor coste para funcionalidades enterprise. Mejor adaptado para B2C.

Implementacion JWT personalizada

Control maximo y sin dependencia de proveedor. Pero: requiere construir flujos de login, gestion de sesiones, refresco de tokens, endpoints JWKS, MFA, integraciones SSO -- esfuerzo enorme y riesgo de seguridad. No justificado para este tamano de equipo.

Supabase Auth

Buena integracion con el ecosistema Supabase pero no encaja con nuestra arquitectura Cloudflare-first. Soporte limitado de SSO empresarial. Mejor para proyectos nativos de Supabase.