vviudez/api-ldap repository overview

⁠API de autenticacion LDAP, API keys y sesiones

Servicio API construido con Python 3.11+ y FastAPI que actua como capa de autenticacion y gestion de sesiones para otras aplicaciones internas. Sus responsabilidades principales son:

• Autenticar usuarios contra un servidor OpenLDAP (o cualquier directorio compatible con LDAP v3), validando usuario y contrasena mediante un patron de doble bind.
• Emitir y gestionar API keys de larga duracion, pensadas como sustituto de las credenciales LDAP para integraciones automatizadas (scripts, tareas programadas, otros servicios) que no pueden o no deben mantener una sesion basada en cookie.
• Gestionar sesiones de usuario respaldadas por cookie, con su estado persistido en una base de datos relacional (SQLite, MariaDB o PostgreSQL, segun configuracion), lo que permite invalidarlas de forma inmediata y centralizada.
• Registrar en una tabla de auditoria los eventos de seguridad relevantes (inicios de sesion, cierres de sesion, creacion/revocacion de API keys, consultas de grupos).

⁠Arquitectura en alto nivel

                        +---------------------------+
                        |  Cliente (navegador,      |
                        |  script, integracion)     |
                        +-------------+-------------+
                                      | HTTPS
                                      v
                        +----------------------------+
                        |  Proxy reverso             |
                        |  (nginx / traefik)         |
                        |  Termina TLS aqui          |
                        +-------------+--------------+
                                      | HTTP (red interna/privada)
                                      v
                        +----------------------------+
                        |   API FastAPI              |
                        |   (uvicorn, Python 3.11+)  |
                        +---------+---------+--------+
                                  |         |
                   Autenticacion  |         |  Persistencia
                   de usuarios    |         |  (api_keys, user_sessions,
                   (doble bind)   |         |   audit_log)
                                  v         v
                     +------------------+  +----------------------------+
                     |  Servidor(es)    |  |  Base de datos             |
                     |  OpenLDAP /      |  |  SQLite / MariaDB /        |
                     |  compatible      |  |  PostgreSQL (segun config) |
                     +------------------+  +----------------------------+

La API nunca guarda contrasenas de usuario ni valores en claro de API keys o tokens de sesion: solo un hash HMAC-SHA256 de estos ultimos (ver docs/SECURITY.md⁠).

⁠Endpoints principales

Todos ellos viven bajo el prefijo /api/v1/auth:

Ademas, la API expone GET /api/v1/health como comprobacion de vida del servicio (sin autenticacion). El detalle completo de peticiones/respuestas esta en docs/API.md⁠ y, de forma interactiva, en Swagger UI (/docs).

⁠Puesta en marcha rapida (quick start)

# 1. Clonar el repositorio
git clone <url-del-repositorio> api
cd api

# 2. Copiar y ajustar la configuracion
cp config/config.example.yaml config/config.yaml
# Editar config/config.yaml: servidores LDAP, motor de base de datos, IPs permitidas, etc.

# 3. Copiar y completar las variables de entorno (secretos)
cp .env.example .env
# Editar .env: API_SECRET_KEY, LDAP_BIND_PASSWORD y, si aplica, DB_PASSWORD.

# 4. Arrancar el servicio en modo desarrollo
#    (crea automaticamente un entorno virtual en ./venv, instala requirements.txt
#    y lanza uvicorn con recarga automatica)
scripts/run_dev.sh

# Si se usa MariaDB o PostgreSQL en lugar de SQLite, instalar ademas, dentro de
# ese mismo entorno virtual, el driver correspondiente antes de arrancar:
#   source venv/bin/activate
#   pip install -r requirements-mariadb.txt      # o requirements-postgresql.txt

# 5. Abrir la documentacion interactiva
#    http://localhost:8000/docs   (Swagger UI)
#    http://localhost:8000/redoc  (ReDoc)

Ademas de fijar la cookie de sesion habitual, POST /login devuelve tambien un access_token de tipo bearer en el cuerpo de la respuesta, pensado para pegarlo directamente en el boton "Authorize" de Swagger UI y probar asi los endpoints protegidos desde /docs (ver docs/API.md⁠).

Para una instalacion detallada (incluyendo la creacion del esquema de base de datos con los scripts SQL de sql/), ver docs/INSTALL.md⁠.

⁠Docker

El servicio tambien puede empaquetarse como imagen Docker, pensada para montarse con dos volumenes externos (/config para el config.yaml real y /data para persistir la base de datos SQLite y los logs) e instala de fabrica los drivers de los tres motores de base de datos soportados. Arranque minimo:

docker build -t api-ldap:latest .
docker run -d -p 8000:8000 -v $(pwd)/config:/config:ro -v $(pwd)/data:/data --env-file .env api-ldap:latest

Ver docs/DOCKER.md⁠ para el detalle completo (incluye tambien el docker-compose.yml incluido en el repositorio).

⁠Documentacion

• docs/INSTALL.md⁠ — instalacion paso a paso.
• docs/DOCKER.md⁠ — empaquetado y ejecucion como imagen Docker.
• docs/CONFIGURATION.md⁠ — referencia completa de config/config.yaml.
• docs/API.md⁠ — documentacion de los endpoints (request/response, codigos de estado, autenticacion).
• docs/DATABASE.md⁠ — modelo de datos, indices, vistas y scripts SQL por motor.
• docs/LDAP.md⁠ — configuracion LDAP, pool de servidores y patron de doble bind.
• docs/SECURITY.md⁠ — decisiones de seguridad del proyecto.

⁠Nota sobre despliegue en produccion

Este servicio esta diseñado para ejecutarse detras de un proxy reverso (nginx, traefik o equivalente) en cualquier entorno de produccion. El proxy reverso es quien debe terminar TLS (certificado HTTPS) y reenviar el trafico a la API por HTTP en una red interna/privada; la propia API no implementa terminacion TLS. Ver tambien la recomendacion de filtrado de IPs de origen y demas medidas de seguridad en docs/SECURITY.md⁠.