ADR-0001 — Keycloak como proveedor de identidad¶


Estado	Accepted
Fecha	2026-01-15
Revisión	2027-01-15
Autores	Equipo de plataforma

Contexto¶

La plataforma necesita una solución de gestión de identidad y acceso (IAM) que cumpla con:

Autenticación centralizada para aplicaciones internas y portales de partners.
Soporte completo de OAuth 2.0 y OpenID Connect.
Multi-tenancy mediante aislamiento de realms.
Integración con directorios LDAP/Active Directory corporativos.
Auto-hospedado (on-premise / VPS) por requisitos de privacidad y control.
Sin dependencia de proveedores SaaS externos para funcionalidad core.

Opciones consideradas¶

Opción	Pros	Contras
Keycloak (seleccionado)	Open source, estándar OAuth2/OIDC completo, multi-tenant con realms, extensible, LDAP/AD nativo, comunidad activa, RedHat soporte	JVM (memoria), configuración compleja, UI de admin mejorable
Desarrollar IAM propio	Control total, mínimo overhead	Costo de desarrollo y mantenimiento enorme; no recomendable por seguridad
Auth0 / Okta	SaaS gestionado, fácil configuración	Coste elevado en escala, datos en terceros, dependencia de proveedor
Zitadel	Moderno, cloud-native, buen UX de admin	Ecosistema más pequeño, menos extensiones, menor adopción enterprise
Authentik	Interfaz moderna, Python	Menor adopción enterprise, rendimiento a escala por validar

Decisión¶

Se adopta Keycloak 26.x como proveedor de identidad central de la plataforma.

Justificación¶

Estándares completos: Implementa OAuth 2.0, OAuth 2.1, OpenID Connect Core, PKCE, Device Flow, Token Exchange y FAPI. No hay que implementar nada del protocolo manualmente.
Multi-tenancy nativo: Los Realms de Keycloak proporcionan aislamiento completo de usuarios, clientes y configuración entre realm-internal y realm-partners sin configuración adicional.
Federación de identidad: LDAP/AD federation nativa sin plugins. Identity brokering con Google, Azure AD, SAML 2.0 out-of-the-box.
Extensibilidad: Service Provider Interfaces (SPI) para flujos de autenticación personalizados, mappers de claims, user storage providers y event listeners.
Ecosistema Spring: Integración de primera clase con Spring Security (spring-boot-starter-oauth2-resource-server) y Spring Boot Actuator.
Operación VPS: Imagen Docker oficial, modo --optimized para producción, PostgreSQL como backend robusto.
Sin vendor lock-in: Estándar OIDC significa que cualquier cliente OAuth2 compatible funciona sin cambios.

Consecuencias¶

Positivas¶

Cero código de IAM que mantener: toda la lógica de autenticación está en Keycloak.
Actualizaciones de seguridad gestionadas por el proyecto Keycloak (RedHat).
Los desarrolladores de aplicaciones solo necesitan configurar issuer-uri en application.yml.
Admin Console para gestión sin código.
Audit log integrado de todos los eventos de autenticación.

Negativas / Riesgos¶

Memoria JVM: Keycloak requiere mínimo 512 MB de heap. En VPS pequeños puede ser limitante.
Mitigación: Configurar KC_OPTS=-Xms256m -Xmx512m y monitorear con Prometheus.
Complejidad de configuración inicial: La curva de aprendizaje de Keycloak (realms, clients, flows) es significativa.
Mitigación: Importar configuración base versionada en el repositorio (realm-export.json).
Dependencia única de identidad: Si Keycloak no está disponible, ningún usuario puede autenticarse.
Mitigación: Configurar health checks y alertas. En v1.1 añadir un segundo nodo Keycloak con sesiones compartidas.
Actualización de versiones: Las migraciones de Keycloak entre versiones mayores requieren atención.
Mitigación: Documentar el proceso de upgrade y probar en staging antes de producción.

Revisión¶

Esta decisión se revisará en enero 2027 evaluando: - Madurez de Zitadel para cargas enterprise. - Disponibilidad de Keycloak 27.x+ y sus mejoras de rendimiento. - Necesidad de clusterización y su complejidad operacional.