---
id: "US-AUTH-003"
title: "Login con Google"
type: "User Story"
status: "Done"
priority: "Alta"
epic: "OQI-001"
story_points: 5
created_date: "2025-12-05"
updated_date: "2026-01-04"
---

# US-AUTH-003: Login con Google

**Version:** 1.0.0
**Fecha:** 2025-12-05
**Estado:** ✅ Implementado
**Story Points:** 5
**Prioridad:** P0 (Crítica)
**Épica:** [OQI-001](../_MAP.md)

---

## Historia de Usuario

**Como** visitante de Trading Platform
**Quiero** poder iniciar sesión con mi cuenta de Google
**Para** acceder rápidamente sin crear nuevas credenciales

---

## Criterios de Aceptación

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

**Dado** que estoy en la página de login o registro
**Cuando** veo las opciones de inicio de sesión
**Entonces** debería ver un botón "Continuar con Google" claramente visible

### AC-002: Redirección a Google

**Dado** que hago click en "Continuar con Google"
**Cuando** se inicia el flujo OAuth
**Entonces** debería ser redirigido a la página de autorización de Google

### AC-003: Autorización exitosa (usuario nuevo)

**Dado** que autorizo el acceso en Google
**Y** mi email de Google no está registrado en Trading Platform
**Cuando** Google me redirige de vuelta
**Entonces** debería:
1. Crear una nueva cuenta automáticamente
2. Usar mis datos de Google (nombre, email, foto)
3. Marcar mi email como verificado
4. Iniciar sesión automáticamente
5. Ser redirigido al dashboard

### AC-004: Autorización exitosa (usuario existente)

**Dado** que autorizo el acceso en Google
**Y** mi email de Google ya está registrado en Trading Platform
**Cuando** Google me redirige de vuelta
**Entonces** debería:
1. Vincular Google a mi cuenta existente
2. Iniciar sesión automáticamente
3. Ser redirigido al dashboard

### AC-005: Cancelación de autorización

**Dado** que hago click en "Continuar con Google"
**Cuando** cancelo la autorización en Google
**Entonces** debería:
1. Ser redirigido a la página de login
2. Ver un mensaje "Autorización cancelada"

### AC-006: Error de Google

**Dado** que hago click en "Continuar con Google"
**Cuando** ocurre un error con Google
**Entonces** debería:
1. Ser redirigido a la página de login
2. Ver un mensaje "Error al conectar con Google. Intenta de nuevo."

### AC-007: Desvinculación de Google

**Dado** que tengo Google vinculado a mi cuenta
**Y** tengo otro método de autenticación activo
**Cuando** intento desvincular Google desde configuración
**Entonces** debería poder desvincularlo exitosamente

### AC-008: Protección de último método

**Dado** que Google es mi único método de autenticación
**Cuando** intento desvincularlo
**Entonces** debería ver un mensaje "No puedes eliminar tu único método de acceso"

---

## Flujo Visual

```
┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│  PASO 1: Click en Google                                                 │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │              Inicia sesión en Trading Platform                           │ │
│  │                                                                    │ │
│  │  ┌──────────────────────────────────────────────────────────────┐│ │
│  │  │  🔵 Continuar con Google                              →      ││ │
│  │  └──────────────────────────────────────────────────────────────┘│ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 2: Autorización en Google                                          │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  ┌────────────────────────────────────────────────────────────┐  │ │
│  │  │                         Google                              │  │ │
│  │  │                                                             │  │ │
│  │  │  Trading Platform quiere acceder a tu cuenta de Google         │  │ │
│  │  │                                                             │  │ │
│  │  │  Esto permitirá a Trading Platform:                            │  │ │
│  │  │  • Ver tu dirección de correo electrónico                  │  │ │
│  │  │  • Ver tu información personal básica                      │  │ │
│  │  │                                                             │  │ │
│  │  │  [Cancelar]                              [Permitir]        │  │ │
│  │  │                                                             │  │ │
│  │  └────────────────────────────────────────────────────────────┘  │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 3: Redirección exitosa                                             │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  ┌──────────────────────────────────────────────────────────────┐│ │
│  │  │                                                              ││ │
│  │  │  ⏳ Completando inicio de sesión...                          ││ │
│  │  │                                                              ││ │
│  │  └──────────────────────────────────────────────────────────────┘│ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                              │                                           │
│                              ▼                                           │
│  PASO 4: Dashboard                                                       │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                                                                    │ │
│  │  ¡Bienvenido, Juan! 👋                                            │ │
│  │                                                                    │ │
│  │  Dashboard...                                                      │ │
│  │                                                                    │ │
│  └────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## Datos Obtenidos de Google

| Campo | Uso |
|-------|-----|
| `id` | `provider_user_id` en oauth_accounts |
| `email` | Email del usuario (si no tiene) |
| `verified_email` | Marcar email como verificado |
| `given_name` | Nombre del usuario |
| `family_name` | Apellido del usuario |
| `picture` | Avatar del usuario |

---

## Notas Técnicas

### Configuración Google Cloud Console

1. Crear proyecto en Google Cloud Console
2. Habilitar Google+ API
3. Configurar OAuth consent screen
4. Crear OAuth 2.0 credentials
5. Agregar redirect URIs autorizados

### Variables de Entorno

```env
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx
GOOGLE_CALLBACK_URL=https://api.trading.com/auth/oauth/google/callback
```

### Scopes Solicitados

```javascript
const scopes = ['profile', 'email'];
```

### Frontend

- Componente: `apps/frontend/src/modules/auth/components/SocialLoginButtons.tsx`
- Callback: `apps/frontend/src/modules/auth/pages/AuthCallback.tsx`

### Backend

- Service: `apps/backend/src/modules/auth/services/oauth.service.ts`
- Endpoint: `POST /api/v1/auth/oauth/google`

---

## Errores Comunes

| Error | Causa | Solución |
|-------|-------|----------|
| `invalid_client` | Client ID incorrecto | Verificar configuración |
| `redirect_uri_mismatch` | URL no autorizada | Agregar URL en Google Console |
| `access_denied` | Usuario canceló | Mostrar mensaje amigable |

---

## Requerimientos Relacionados

- [RF-AUTH-001: OAuth Multi-proveedor](../requerimientos/RF-AUTH-001-oauth.md)

## Especificaciones Relacionadas

- [ET-AUTH-001: OAuth Providers](../especificaciones/ET-AUTH-001-oauth.md)