---
id: "US-AUTH-004"
title: "OAuth Facebook"
type: "User Story"
status: "To Do"
priority: "Alta"
epic: "OQI-001"
story_points: 3
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-AUTH-004: OAuth Facebook

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** Pendiente
**Story Points:** 3
**Prioridad:** P1 (Alta)
**Épica:** [OQI-001](../_MAP.md)

---

## Historia de Usuario

**Como** visitante o usuario de Trading Platform
**Quiero** poder registrarme e iniciar sesión usando mi cuenta de Facebook
**Para** tener un acceso rápido y sencillo sin crear una nueva contraseña

---

## Criterios de Aceptación

### AC-001: Botón de Facebook visible

**Dado** que estoy en la página de registro o login
**Cuando** veo las opciones de autenticación
**Entonces** debería ver un botón "Continuar con Facebook"
**Y** debería tener el color y logo oficial de Facebook

### AC-002: Flujo de OAuth

**Dado** que hago click en "Continuar con Facebook"
**Cuando** se abre la ventana de Facebook
**Entonces** debería:
1. Ver la pantalla de autorización de Facebook
2. Poder revisar los permisos solicitados
3. Poder autorizar o cancelar

### AC-003: Permisos solicitados

**Dado** que estoy en la pantalla de autorización de Facebook
**Cuando** reviso los permisos
**Entonces** la app debería solicitar únicamente:
- Email
- Nombre público
- Foto de perfil

### AC-004: Primer registro exitoso

**Dado** que es mi primera vez usando Facebook OAuth
**Cuando** autorizo los permisos
**Entonces** debería:
1. Crear mi cuenta automáticamente
2. Recibir un JWT token
3. Ser redirigido al dashboard
4. Ver mi nombre y foto de Facebook
5. NO necesitar verificación de email

### AC-005: Login existente

**Dado** que ya tengo una cuenta vinculada con Facebook
**Cuando** uso "Continuar con Facebook"
**Entonces** debería:
1. Iniciar sesión automáticamente
2. Ser redirigido al dashboard
3. NO ver pantalla de registro

### AC-006: Email ya registrado con otro método

**Dado** que mi email de Facebook ya está registrado con email/password
**Cuando** intento usar Facebook OAuth
**Entonces** debería ver un mensaje:
- "Este email ya está registrado. ¿Deseas vincular tu cuenta de Facebook?"
**Y** debería poder vincular las cuentas

### AC-007: Cancelación del flujo

**Dado** que inicio el flujo de Facebook OAuth
**Cuando** cancelo en la ventana de Facebook
**Entonces** debería:
1. Volver a la página de login/registro
2. Ver un mensaje "Autenticación cancelada"
3. Poder intentar con otro método

### AC-008: Error de Facebook

**Dado** que hay un error en el servicio de Facebook
**Cuando** intento autenticarme
**Entonces** debería ver un mensaje:
- "Error al conectar con Facebook. Intenta más tarde"
**Y** debería poder usar otro método de autenticación

---

## Mockup

```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│              🌟 Bienvenido a Trading Platform                     │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               📧 Email                               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          🔵 Continuar con Facebook                   │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               🔴 Continuar con Google                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  [Twitter/X]  [Apple]  [GitHub]                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Ventana de Facebook OAuth:
┌─────────────────────────────────────────────────────────────┐
│  facebook.com                                          ✕    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│              Trading Platform desea acceder a:                     │
│                                                             │
│  ✓ Tu nombre y foto de perfil                              │
│  ✓ Tu dirección de email                                   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Continuar como Juan Pérez               │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Cancelar                                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Tareas Técnicas

### Database (DB)

- [ ] Agregar campos a tabla `users`:
  ```sql
  ALTER TABLE users ADD COLUMN facebook_id VARCHAR(255) UNIQUE;
  ALTER TABLE users ADD COLUMN avatar_url TEXT;
  ```
- [ ] Tabla `oauth_connections`:
  ```sql
  CREATE TABLE oauth_connections (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    provider VARCHAR(50), -- 'facebook', 'google', etc
    provider_user_id VARCHAR(255),
    access_token TEXT,
    refresh_token TEXT,
    token_expires_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(provider, provider_user_id)
  );
  ```

### Backend (BE)

- [ ] Configurar Facebook App en Meta Developers
- [ ] Obtener App ID y App Secret
- [ ] Endpoint `GET /api/v1/auth/facebook`
  - Redirige a Facebook OAuth
- [ ] Endpoint `GET /api/v1/auth/facebook/callback`
  - Recibe código de autorización
  - Intercambia por access token
  - Obtiene datos del usuario
  - Crea o actualiza usuario
  - Genera JWT token
- [ ] Service `FacebookOAuthService`
  - `getAuthorizationUrl()`
  - `exchangeCodeForToken()`
  - `getUserProfile()`
  - `linkAccount()`
- [ ] Manejo de refresh tokens
- [ ] Tests unitarios (8 casos)
- [ ] Tests de integración con mock de Facebook API

### Frontend (FE)

- [ ] Botón "Continuar con Facebook"
- [ ] Manejo de popup o redirect de OAuth
- [ ] Recepción de callback
- [ ] Almacenamiento de token JWT
- [ ] Estado de loading durante OAuth
- [ ] Manejo de errores
- [ ] Modal de vinculación de cuentas
- [ ] Tests con React Testing Library

### Testing (QA)

- [ ] E2E: Registro nuevo con Facebook
- [ ] E2E: Login existente con Facebook
- [ ] E2E: Vinculación de cuentas
- [ ] E2E: Cancelación del flujo
- [ ] E2E: Permisos rechazados
- [ ] Test de seguridad: Validación de tokens
- [ ] Test de seguridad: CSRF protection
- [ ] Mock de Facebook API para tests

---

## Dependencias

- **Bloqueantes:**
  - Cuenta de Facebook Developer
  - Configuración de dominio verificado
  - SSL/HTTPS en producción

- **Deseables:**
  - US-AUTH-003: Para mantener consistencia con Google OAuth

---

## Definition of Ready (DoR)

- [ ] Facebook App creada y configurada
- [ ] Credenciales de desarrollo disponibles
- [ ] Mockups aprobados
- [ ] API contract definido
- [ ] Política de privacidad publicada (requerido por Facebook)

---

## Definition of Done (DoD)

- [ ] Código implementado y revisado
- [ ] Tests unitarios con 80%+ cobertura
- [ ] Tests de integración pasando
- [ ] Tests E2E implementados
- [ ] Facebook App Review aprobado (para producción)
- [ ] Documentación actualizada
- [ ] Manejo de errores completo
- [ ] Logs implementados
- [ ] QA aprobado en staging
- [ ] Deploy a producción exitoso

---

## Notas Técnicas

### Facebook OAuth Flow

1. Frontend redirige a `/api/v1/auth/facebook`
2. Backend redirige a Facebook con:
   - `client_id`
   - `redirect_uri`
   - `scope=email,public_profile`
   - `state` (CSRF token)
3. Usuario autoriza en Facebook
4. Facebook redirige a `redirect_uri` con `code`
5. Backend intercambia `code` por `access_token`
6. Backend obtiene perfil del usuario
7. Backend crea/actualiza usuario
8. Backend genera JWT y redirige a frontend

### Facebook API Endpoints

- Authorization: `https://www.facebook.com/v18.0/dialog/oauth`
- Token exchange: `https://graph.facebook.com/v18.0/oauth/access_token`
- User info: `https://graph.facebook.com/v18.0/me?fields=id,name,email,picture`

### Environment Variables

```env
FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_CALLBACK_URL=https://trading.com/api/v1/auth/facebook/callback
```

### Security Considerations

- Validar `state` parameter para prevenir CSRF
- No almacenar access tokens en localStorage
- Usar refresh tokens cuando sea posible
- Validar que el email viene de Facebook
- Rate limiting en endpoints de OAuth

---

## Requerimientos Relacionados

- [RF-AUTH-003: OAuth Social](../requerimientos/RF-AUTH-003-oauth.md)

## Especificaciones Relacionadas

- [ET-AUTH-002: JWT Tokens](../especificaciones/ET-AUTH-002-jwt.md)
- [ET-AUTH-004: OAuth Integration](../especificaciones/ET-AUTH-004-oauth.md)