🔐 Sistema de Autenticación con AWS Cognito y MFA

Un sistema completo de autenticación construido con Express.js, React, TypeScript y AWS Cognito, que incluye autenticación de dos factores (MFA) sin necesidad de acceder a la consola de AWS.

🚀 Características

✅ Funcionalidades Implementadas

• 🔐 Autenticación Completa

  • Registro de usuarios con validación de email
  • Login con credenciales
  • Confirmación de registro por email
  • Logout seguro
  • Gestión de tokens JWT

• 🔒 Autenticación de Dos Factores (MFA)

  • Configuración de MFA con QR Code
  • Verificación de códigos TOTP
  • Códigos de respaldo para emergencias
  • Verificación local para testing
  • Integración con aplicaciones como Google Authenticator, Authy, etc.

• 👥 Gestión de Usuarios

  • Listado de usuarios
  • Actualización de perfiles
  • Eliminación de usuarios
  • Visualización de estados (activo/inactivo, MFA habilitado)

• 🔧 Funcionalidades Adicionales

  • Cambio de contraseña
  • Recuperación de contraseña
  • Validaciones robustas
  • Manejo de errores detallado
  • Rate limiting
  • Seguridad con Helmet

🏗️ Arquitectura

cognito/
├── src/                    # Backend (Express.js + TypeScript)
│   ├── config/            # Configuración de AWS
│   ├── controllers/       # Controladores de la API
│   ├── routes/           # Rutas de la API
│   ├── services/         # Servicios de negocio
│   ├── types/            # Tipos TypeScript
│   └── server.ts         # Servidor principal
├── client/               # Frontend (React + TypeScript)
│   ├── src/
│   │   ├── components/   # Componentes React
│   │   ├── contexts/     # Contexto de autenticación
│   │   ├── services/     # Servicios de API
│   │   └── types/        # Tipos TypeScript
│   └── package.json
├── package.json          # Dependencias del backend
└── README.md

🛠️ Tecnologías Utilizadas

Backend

• Node.js + Express.js
• TypeScript
• AWS SDK v2 para Cognito
• Speakeasy para generación de códigos TOTP
• QRCode para generación de códigos QR
• Helmet para seguridad
• CORS para comunicación entre dominios
• Rate Limiting para protección contra ataques

Frontend

• React 18 con TypeScript
• Vite como bundler
• React Router para navegación
• Axios para llamadas HTTP
• Context API para estado global

📋 Prerrequisitos

AWS Cognito Setup

Antes de ejecutar el proyecto, necesitas configurar AWS Cognito:

1. Crear User Pool en AWS Cognito
2. Configurar App Client
3. Habilitar MFA (Software Token)
4. Configurar políticas de contraseña
5. Configurar triggers de email (opcional)

Variables de Entorno Requeridas

Backend (.env)

# AWS Cognito Configuration
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key

# Cognito User Pool
COGNITO_USER_POOL_ID=us-east-1_xxxxxxxxx
COGNITO_CLIENT_ID=your_client_id
COGNITO_CLIENT_SECRET=your_client_secret

# Server Configuration
PORT=3001
NODE_ENV=development

# JWT Secret for additional security
JWT_SECRET=your_jwt_secret_key_here

# Frontend URL for CORS
FRONTEND_URL=http://localhost:5173

# MFA Configuration
MFA_ENABLED=true
MFA_ISSUER=CognitoAuthSystem

Frontend (client/.env)

VITE_API_URL=http://localhost:3001/api

🚀 Instalación y Configuración

1. Clonar y Instalar Dependencias

# Instalar dependencias del backend
npm install

# Instalar dependencias del frontend
cd client
npm install
cd ..

2. Configurar Variables de Entorno

# Copiar archivos de ejemplo
cp env.example .env
cd client
cp env.example .env
cd ..

# Editar las variables con tus credenciales de AWS

3. Configurar AWS Cognito

Crear User Pool:

1. Ve a AWS Console → Cognito → User Pools
2. Crea un nuevo User Pool
3. Configura las políticas de contraseña:
   • Mínimo 8 caracteres
   • Requerir mayúsculas, minúsculas y números
   • Requerir caracteres especiales (opcional)

Configurar App Client:

1. En tu User Pool, ve a "App clients"
2. Crea un nuevo app client
3. Habilita "USER_PASSWORD_AUTH" en Authentication flows
4. Guarda el Client ID y Client Secret

Habilitar MFA:

1. En tu User Pool, ve a "Sign-in experience"
2. En "Multi-factor authentication", selecciona "Optional"
3. En "MFA methods", habilita "Software token MFA (TOTP)"

4. Ejecutar el Proyecto

# Desarrollo (ambos servidores)
npm run dev

# O ejecutar por separado:
# Backend
npm run dev:server

# Frontend (en otra terminal)
npm run dev:client

📱 Uso del Sistema

1. Registro de Usuario

1. Ve a /register
2. Completa el formulario con:
   • Usuario único
   • Email válido
   • Contraseña que cumpla los requisitos
3. Confirma el registro con el código enviado por email

2. Configuración de MFA

1. Inicia sesión en /login
2. En el dashboard, configura MFA
3. Escanea el código QR con tu aplicación de autenticación
4. Verifica la configuración con un código de prueba

3. Login con MFA

1. Inicia sesión con tus credenciales
2. Si MFA está habilitado, ingresa el código de tu aplicación
3. Accede al dashboard

4. Gestión de Usuarios

• Ver perfil: Información personal y estado de MFA
• Gestionar usuarios: Listar, actualizar y eliminar usuarios
• Cambiar contraseña: Actualizar credenciales de forma segura

🔧 API Endpoints

Autenticación

• POST /api/auth/register - Registrar usuario
• POST /api/auth/confirm-registration - Confirmar registro
• POST /api/auth/login - Iniciar sesión
• POST /api/auth/logout - Cerrar sesión

MFA

• POST /api/auth/setup-mfa - Configurar MFA
• POST /api/auth/verify-mfa - Verificar código MFA
• POST /api/auth/verify-mfa-local - Verificación local

Gestión de Usuarios

• GET /api/auth/user/info - Obtener información del usuario
• GET /api/auth/users - Listar usuarios
• PUT /api/auth/user/update - Actualizar usuario
• DELETE /api/auth/user/:username - Eliminar usuario

Contraseñas

• POST /api/auth/change-password - Cambiar contraseña
• POST /api/auth/forgot-password - Solicitar restablecimiento
• POST /api/auth/confirm-forgot-password - Confirmar restablecimiento

🔒 Seguridad

Medidas Implementadas

• Rate Limiting: Protección contra ataques de fuerza bruta
• Helmet: Headers de seguridad HTTP
• CORS: Configuración segura para comunicación entre dominios
• Validación: Validación robusta de datos de entrada
• Manejo de Errores: Errores seguros sin exposición de información sensible
• Tokens JWT: Gestión segura de tokens de autenticación

MFA Security

• TOTP: Códigos de tiempo único (RFC 6238)
• QR Codes: Configuración fácil con aplicaciones estándar
• Backup Codes: Códigos de emergencia para recuperación
• Verificación Local: Testing sin comprometer seguridad

🧪 Testing

Verificación MFA Local

El sistema incluye una función de verificación local para testing:

// En el frontend, puedes verificar códigos MFA localmente
const response = await apiService.verifyMFALocally(secret, token);

Health Check

curl http://localhost:3001/health

🚨 Troubleshooting

Problemas Comunes

1. Error de configuración AWS

   • Verifica que las credenciales de AWS sean correctas
   • Asegúrate de que el User Pool y App Client existan
   • Confirma que MFA esté habilitado en el User Pool

2. Error de CORS

   • Verifica que FRONTEND_URL esté configurado correctamente
   • Asegúrate de que el frontend esté corriendo en el puerto correcto

3. Error de MFA

   • Verifica que la aplicación de autenticación esté sincronizada
   • Usa los códigos de respaldo si es necesario
   • Confirma que el secreto se haya configurado correctamente

4. Error de validación

   • Verifica que las contraseñas cumplan los requisitos
   • Asegúrate de que el email tenga formato válido
   • Confirma que el usuario no exista ya

📚 Documentación Adicional

AWS Cognito

• AWS Cognito User Pools
• MFA Configuration
• Authentication Flows

TOTP/MFA

• RFC 6238 - TOTP
• Google Authenticator
• Authy

---

🎯 Próximas Mejoras

• Integración con PrimeReact para UI mejorada
• Soporte para múltiples proveedores de MFA
• Dashboard administrativo avanzado
• Logs de auditoría
• Integración con otros servicios AWS
• Tests automatizados
• Dockerización del proyecto
• CI/CD pipeline

---