Auth System Backend

Sistema de autenticación completo con MFA (Multi-Factor Authentication) construido con FastAPI, MongoDB y Prometheus.

Características

• Autenticación JWT: Tokens seguros con expiración configurable
• MFA/TOTP: Autenticación de dos factores con Google Authenticator
• MongoDB: Base de datos NoSQL para almacenamiento de usuarios
• Prometheus: Métricas y monitoreo integrado
• Validación: Esquemas Pydantic para validación de datos
• Hash de contraseñas: bcrypt para almacenamiento seguro
• CORS: Configurado para desarrollo y producción

Stack Tecnológico

• FastAPI: Framework web moderno y rápido
• UV: Gestor de dependencias y entornos virtuales
• MongoDB: Base de datos NoSQL
• Motor: Driver async para MongoDB
• PyJWT: Manejo de tokens JWT
• Passlib: Hash de contraseñas con bcrypt
• PyOTP: Generación de códigos TOTP para MFA
• QRCode: Generación de códigos QR para MFA setup
• Prometheus Client: Métricas y monitoreo

Estructura del Proyecto

backend/
├── app/
│   ├── auth/
│   │   └── routes.py          # Endpoints de autenticación
│   ├── database/
│   │   ├── connection.py      # Configuración MongoDB
│   │   └── users.py          # CRUD de usuarios
│   ├── models/
│   │   └── user.py           # Modelos de datos
│   ├── schemas/
│   │   └── user.py           # Esquemas Pydantic
│   └── utils/
│       └── security.py       # Utilidades de seguridad
├── main.py                   # Punto de entrada de la aplicación
├── pyproject.toml           # Configuración del proyecto
└── .env                     # Variables de entorno

Instalación

Requisitos

• Python 3.13+
• UV (gestor de dependencias)
• MongoDB (local o containerizado)

Configuración

1. Clonar el repositorio

git clone <tu-repo>
cd backend

2. Instalar dependencias con UV

uv sync

3. Configurar variables de entorno

cp .env.example .env
# Editar .env con tus configuraciones

4. Ejecutar MongoDB (con Docker)

docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password123 \
  mongo:7

5. Ejecutar la aplicación

uv run python main.py

Variables de Entorno

# MongoDB
MONGODB_URL=mongodb://admin:password123@localhost:27017
DATABASE_NAME=auth_db

# JWT
SECRET_KEY=tu-super-secret-key-muy-segura
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# App
APP_NAME=Auth API
DEBUG=true

Endpoints API

Autenticación

• POST /auth/register - Registrar nuevo usuario
• POST /auth/login - Iniciar sesión
• GET /auth/me - Obtener perfil del usuario (requiere token)

MFA (Multi-Factor Authentication)

• POST /auth/mfa/setup - Configurar MFA (genera QR code)
• POST /auth/mfa/verify - Verificar y activar MFA

Sistema

• GET /health - Health check de la aplicación
• GET /metrics - Métricas de Prometheus
• GET /docs - Documentación automática (Swagger UI)

Uso de la API

1. Registro de Usuario

curl -X POST "http://localhost:8000/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "usuario",
    "email": "[email protected]",
    "password": "password123"
  }'

2. Login

curl -X POST "http://localhost:8000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123"
  }'

3. Acceso a endpoints protegidos

curl -X GET "http://localhost:8000/auth/me" \
  -H "Authorization: Bearer <tu_token_jwt>"

Docker

Desarrollo

# Usando docker-compose
docker-compose up backend

Dockerfile

FROM python:3.13-slim

RUN pip install uv

WORKDIR /app

COPY pyproject.toml uv.lock* ./
RUN uv sync --frozen

COPY . .

CMD ["uv", "run", "python", "main.py"]

Desarrollo

Linting y Formateo

# Linting
uv run ruff check .

# Formateo
uv run ruff format .

# Fix automático
uv run ruff check --fix .

Testing

# Ejecutar tests
uv run pytest

# Con coverage
uv run pytest --cov=app

Métricas y Monitoreo

La aplicación expone métricas en /metrics para Prometheus:

• fastapi_requests_total - Total de requests por endpoint
• fastapi_request_duration_seconds - Duración de requests

Configuración Prometheus

scrape_configs:
  - job_name: 'fastapi-backend'
    static_configs:
      - targets: ['localhost:8000']
    metrics_path: '/metrics'

Seguridad

• Contraseñas hasheadas con bcrypt
• Tokens JWT con expiración configurable
• MFA/TOTP para autenticación de dos factores
• Validación de datos con Pydantic
• CORS configurado apropiadamente

Contribución

1. Fork el proyecto
2. Crear branch para feature (git checkout -b feature/nueva-feature)
3. Commit cambios (git commit -am 'Agregar nueva feature')
4. Push al branch (git push origin feature/nueva-feature)
5. Crear Pull Request

Licencia

Este proyecto está bajo la licencia MIT. Ver LICENSE para más detalles.

Autor

Jorge Chávez - kubos777