---
id: "ADR-002"
title: "Autenticacion con JWT y OAuth 2.0"
type: "ADR"
status: "Accepted"
priority: "P0"
supersedes: "N/A"
superseded_by: "N/A"
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "2026-01-10"
---

# ADR-002: Autenticación con JWT y OAuth 2.0

## Metadata
| Campo | Valor |
|-------|-------|
| ID | ADR-002 |
| Estado | Accepted |
| Fecha | 2026-01-10 |
| Supersede | N/A |

## Contexto

Template SaaS necesita un sistema de autenticación robusto que soporte:
- Login tradicional con email/password
- Autenticación social (OAuth)
- Multi-Factor Authentication (MFA)
- Sesiones persistentes y seguras
- API stateless para escalabilidad

## Opciones Consideradas

### Opción 1: Session-based Authentication
**Descripción:** Sesiones almacenadas en servidor, cookie con session ID.

**Pros:**
- Simple de implementar
- Revocación inmediata
- Menor payload en requests

**Contras:**
- Requiere almacenamiento de sesiones
- No escalable horizontalmente sin sticky sessions
- Problemas con múltiples dominios/apps

### Opción 2: JWT con Refresh Tokens ✓
**Descripción:** Access tokens cortos + refresh tokens largos.

**Pros:**
- Stateless (escalable horizontalmente)
- Información en token (claims)
- Funciona con múltiples servicios
- Ideal para SPAs y mobile

**Contras:**
- Revocación requiere blacklist
- Tokens más grandes
- Complejidad de refresh flow

### Opción 3: OAuth-only (delegado)
**Descripción:** Usar solo proveedores externos (Google, etc).

**Pros:**
- Sin manejo de passwords
- Seguridad delegada
- UX familiar

**Contras:**
- Dependencia de terceros
- No todos los usuarios tienen cuentas sociales
- Pérdida de control

## Decisión

**Elegimos JWT con Refresh Tokens + OAuth opcional** porque:

1. **Flexibilidad:** Soporta login local y social
2. **Escalabilidad:** Stateless permite escalar horizontalmente
3. **Seguridad:** Access tokens cortos + refresh tokens rotativos
4. **UX:** Sesiones persistentes sin re-login frecuente

## Implementación

### Estructura de Tokens

```typescript
// Access Token (15 min)
{
  sub: 'user-uuid',
  tenant_id: 'tenant-uuid',
  email: 'user@example.com',
  roles: ['admin', 'member'],
  iat: 1234567890,
  exp: 1234568790
}

// Refresh Token (7 días)
{
  sub: 'user-uuid',
  tenant_id: 'tenant-uuid',
  type: 'refresh',
  jti: 'unique-token-id', // para revocación
  iat: 1234567890,
  exp: 1235172690
}
```

### Token Storage

| Token | Almacenamiento | Duración |
|-------|---------------|----------|
| Access Token | Memory/localStorage | 15 min |
| Refresh Token | httpOnly cookie | 7 días |

### OAuth Flow

```
1. Usuario click "Login con Google"
2. Redirect a Google OAuth
3. Google callback con code
4. Backend intercambia code por tokens Google
5. Backend crea/vincula usuario local
6. Backend genera JWT propios
7. Redirect a app con tokens
```

### MFA (TOTP)

```typescript
// Activación
1. Generar secreto TOTP
2. Mostrar QR code
3. Verificar código inicial
4. Guardar secreto encriptado

// Login con MFA
1. Validar email/password
2. Si MFA activo, solicitar código
3. Validar código TOTP
4. Emitir tokens
```

### Endpoints

| Método | Endpoint | Descripción |
|--------|----------|-------------|
| POST | `/auth/register` | Registro nuevo usuario |
| POST | `/auth/login` | Login email/password |
| POST | `/auth/refresh` | Renovar access token |
| POST | `/auth/logout` | Revocar refresh token |
| GET | `/auth/oauth/:provider` | Iniciar OAuth |
| GET | `/auth/oauth/:provider/callback` | Callback OAuth |
| POST | `/auth/mfa/enable` | Activar MFA |
| POST | `/auth/mfa/verify` | Verificar código MFA |

## Consecuencias

### Positivas
- Sistema flexible y escalable
- Soporte para múltiples métodos de auth
- Tokens con información útil (claims)
- Refresh tokens permiten sesiones largas
- Compatible con microservicios

### Negativas
- Complejidad adicional vs sessions
- Requiere manejo cuidadoso de refresh
- Blacklist necesaria para revocación inmediata

### Seguridad Implementada
- Passwords hasheados con bcrypt (cost 12)
- Refresh tokens rotativos (one-time use)
- Rate limiting en endpoints de auth
- CORS restrictivo
- HTTPS obligatorio

## Referencias

- [JWT Best Practices (RFC 8725)](https://tools.ietf.org/html/rfc8725)
- [OAuth 2.0 (RFC 6749)](https://tools.ietf.org/html/rfc6749)
- [TOTP (RFC 6238)](https://tools.ietf.org/html/rfc6238)
- Implementación: `apps/backend/src/modules/auth/`

---

**Fecha decision:** 2026-01-10
**Autores:** Claude Code (Arquitectura)