| id |
title |
type |
project |
version |
updated_date |
| ADR-003-autenticacion-multiproveedor |
Autenticacion Multi-proveedor |
Documentation |
trading-platform |
1.0.0 |
2026-01-04 |
ADR-003: Autenticacion Multi-proveedor
Fecha: 2025-12-05
Estado: ✅ Aceptado
Deciders: Tech Lead, Security Lead
Épica: OQI-001
Contexto
Trading Platform necesita un sistema de autenticacion que:
- Reduzca friccion en el registro (aumentar conversion)
- Soporte multiples metodos de acceso para diferentes usuarios
- Cumpla con estandares de seguridad para plataforma financiera
- Sea extensible para futuros proveedores
- Funcione en mercado LATAM (WhatsApp tiene alta penetracion)
Decision
Implementar autenticacion multi-proveedor con los siguientes metodos:
Proveedores OAuth 2.0
- Google - Mayor adopcion global
- Facebook - Popular en LATAM
- X/Twitter - Comunidad de traders/crypto
- Apple Sign In - Usuarios iOS premium
- GitHub - Desarrolladores, early adopters
Autenticacion Tradicional
- Email/Password - Metodo clasico con verificacion
- Telefono (SMS/WhatsApp) - Via Twilio, popular en LATAM
Seguridad Adicional
- 2FA con TOTP - Google Authenticator compatible
- Backup codes - Recuperacion de cuenta
Tokens
- JWT RS256 para access tokens (15 min)
- Refresh token rotation (7 dias)
- Session management con revocacion
Alternativas Consideradas
Servicios de Auth Gestionados
| Opcion |
Pros |
Contras |
Decision |
| Implementacion propia |
Control total, sin vendor lock-in |
Mas trabajo, responsabilidad seguridad |
✅ Elegido |
| Auth0 |
Feature completo, seguro |
Costo alto en escala, vendor lock-in |
❌ |
| Firebase Auth |
Gratis hasta cierto punto |
Lock-in Google, menos control |
❌ |
| Clerk |
UI bonita, facil |
Nuevo, menos features |
❌ |
| Supabase Auth |
Postgres nativo |
Menos proveedores OAuth |
❌ |
Justificacion: Para una plataforma financiera, el control total sobre autenticacion es critico. Ademas, el costo de Auth0 a escala seria significativo.
Estrategia de Tokens
| Opcion |
Pros |
Contras |
Decision |
| JWT + Refresh rotation |
Stateless, seguro con rotation |
Complejidad de implementacion |
✅ Elegido |
| Sessions en DB |
Simple, revocacion facil |
Stateful, mas queries |
❌ |
| JWT sin refresh |
Simple |
Inseguro (tokens largos) |
❌ |
| Opaque tokens |
Mas seguro |
Requiere lookup en cada request |
❌ |
Algoritmo JWT
| Opcion |
Pros |
Contras |
Decision |
| RS256 |
Verificacion sin secreto |
Keys mas grandes |
✅ Elegido |
| HS256 |
Simple, rapido |
Secreto compartido |
❌ |
| ES256 |
Keys pequeñas |
Menos soporte en librerias |
❌ |
Servicio SMS/WhatsApp
| Opcion |
Pros |
Contras |
Decision |
| Twilio |
Confiable, WhatsApp API |
Costo por mensaje |
✅ Elegido |
| AWS SNS |
Economico |
Sin WhatsApp |
❌ |
| MessageBird |
Bueno para Europa |
Menos soporte LATAM |
❌ |
Diseño de la Solucion
Flujo de Autenticacion
┌─────────────────────────────────────────────────────────────────────────┐
│ AUTHENTICATION FLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Usuario elige metodo de autenticacion │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ OAuth │ │ Email/ │ │ Phone │ │ 2FA │ │
│ │ Providers │ │ Password │ │ OTP │ │ TOTP │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ AUTHENTICATION LAYER │ │
│ │ │ │
│ │ • Validar credenciales │ │
│ │ • Verificar estado de cuenta │ │
│ │ • Verificar 2FA si esta habilitado │ │
│ │ • Rate limiting │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ TOKEN SERVICE │ │
│ │ │ │
│ │ • Generar Access Token (JWT RS256, 15min) │ │
│ │ • Generar Refresh Token (JWT RS256, 7d) │ │
│ │ • Crear sesion en DB │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ SESSION MANAGEMENT │ │
│ │ │ │
│ │ • Almacenar device info │ │
│ │ • Tracking de IP/ubicacion │ │
│ │ • Deteccion de anomalias │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Modelo de Datos
-- Usuario puede tener multiples metodos de auth
users (1) ─────┬───── (N) oauth_accounts
│
├───── (N) sessions
│
├───── (N) email_verifications
│
└───── (N) phone_verifications
Seguridad Implementada
| Medida |
Implementacion |
| Password hashing |
bcrypt cost 12 |
| Token encryption |
AES-256-GCM para OAuth tokens |
| Rate limiting |
5 intentos / 15 min en login |
| Account lockout |
Progresivo (15min, 1h, 24h) |
| Refresh rotation |
Nuevo token en cada refresh |
| Token reuse detection |
Invalida todas las sesiones |
| PKCE |
Para OAuth providers que lo soportan |
| State validation |
Redis con TTL 10 min |
Consecuencias
Positivas
- Mayor conversion: Usuarios pueden registrarse con un click
- Seguridad robusta: 2FA, rotation, rate limiting
- Flexibilidad: Multiples metodos para diferentes segmentos
- Control total: Sin dependencia de servicios externos (excepto OAuth providers)
- Escalable: Facil agregar nuevos proveedores
Negativas
- Complejidad: Mas codigo que usar Auth0
- Mantenimiento: Actualizar integraciones OAuth cuando cambien
- Costo Twilio: SMS/WhatsApp tienen costo por mensaje
- Responsabilidad: Seguridad es nuestra responsabilidad
Riesgos y Mitigaciones
| Riesgo |
Probabilidad |
Impacto |
Mitigacion |
| Breach de tokens |
Baja |
Alto |
Rotation, encryption, short TTL |
| Cambios en OAuth APIs |
Media |
Medio |
Abstraer en servicio, monitorear cambios |
| Abuso de OTP |
Media |
Medio |
Rate limiting agresivo |
| Perdida de 2FA |
Baja |
Alto |
Backup codes, recovery flow |
Metricas de Exito
| Metrica |
Target |
| Conversion registro OAuth |
>40% de registros |
| Tiempo de login (p95) |
<2 segundos |
| Tasa de abandono en registro |
<30% |
| Adopcion de 2FA |
>20% usuarios activos |
| Intentos de login fallidos |
<5% del total |
Referencias
rckrdmrd
c1b5081208