Introducción
Cuando el tema es autenticación y autorización en aplicaciones modernas, la primera reacción de muchos equipos es recurrir a soluciones cloud de pago — Azure Entra ID, AWS Cognito, Auth0 o Firebase Auth. Son servicios excelentes, pero traen costos que pueden sorprender a medida que crece la base de usuarios: planes por MAU (Monthly Active Users), límites de tokens, cobros por login social y MFA. En muchos escenarios, especialmente startups, proyectos personales, entornos on-premises y empresas que valoran la soberanía de los datos, existe una alternativa gratuita, open-source y de nivel enterprise que merece toda la atención: Keycloak.
Keycloak es un servidor de identidad y gestión de acceso mantenido por la Cloud Native Computing Foundation (CNCF) como proyecto en incubación, creado originalmente por Red Hat. Implementa los protocolos OAuth 2.0, OpenID Connect y SAML 2.0 — los mismos que usan Azure Entra ID, Google y otros proveedores de identidad — pero se ejecuta en tu infraestructura, sin costos de licencia, sin límites de usuarios y con control total sobre los datos. Si ya entiendes los fundamentos de autenticación y autorización con JWT, OAuth2 y OpenID Connect, estás listo para el siguiente paso: poner en marcha un identity provider completo con Docker o Podman e integrarlo con tu aplicación ASP.NET Core con C# 8.0+.
En este artículo ejecuto Keycloak en un contenedor, configuro un realm y un client, lo integro con una API REST en C#, personalizo la pantalla de login con logo y tema propios, y lo comparo con los principales proveedores de identidad de la nube. El enfoque es práctico, funcional y 100% gratuito.
💡 Consejo: Aunque los ejemplos de este artículo usan C# con ASP.NET Core, Keycloak es agnóstico de lenguaje y framework. Al implementar protocolos abiertos (OAuth 2.0, OpenID Connect, SAML 2.0), funciona con cualquier tecnología que soporte estos estándares — incluidos Java/Spring Boot, Python/Django/Flask/FastAPI, Node.js/Express/NestJS, Go, PHP/Laravel, Ruby on Rails, Rust y Angular/React/Vue en el front-end. El setup de Keycloak en contenedor y la configuración de realm/client son idénticos sin importar el lenguaje de tu aplicación.
📦 Código fuente: La implementación completa de este artículo está en el repositorio blog-zocateli-sample en GitHub. Clónalo, explóralo y adáptalo a tu contexto.
¿Por Qué Elegir Keycloak?
Costo Cero vs Proveedores Cloud
El principal argumento a favor de Keycloak es simple: no cuesta nada. Mientras los proveedores cloud cobran por usuario activo o por funcionalidad premium, Keycloak lo ofrece todo gratis:
| Funcionalidad | Keycloak (Gratuito) | Azure Entra ID | AWS Cognito | Auth0 |
|---|---|---|---|---|
| Costo base | $0 | Gratis hasta 50.000 MAU (External ID) | Gratis hasta 50.000 MAU | Gratis hasta 7.500 MAU |
| Usuarios ilimitados | ✅ | ❌ (cobra tras el límite) | ❌ (cobra tras el límite) | ❌ (cobra tras el límite) |
| Login social | ✅ Ilimitado | ✅ | ✅ | ✅ (limitado en el plan free) |
| MFA (Multi-Factor) | ✅ Incluido | ✅ | ✅ (costo adicional por SMS) | ✅ (limitado en el plan free) |
| SAML + OIDC | ✅ Ambos | ✅ Ambos | ✅ OIDC / ⚠️ SAML limitado | ✅ Ambos |
| Personalización de UI | ✅ Total (temas FreeMarker) | ⚠️ Limitada | ⚠️ Limitada | ✅ (planes de pago) |
| Self-hosted | ✅ Obligatorio | ❌ Solo SaaS | ❌ Solo SaaS | ⚠️ Plan Enterprise |
| Soberanía de los datos | ✅ Total | ❌ Datos en Microsoft | ❌ Datos en AWS | ❌ Datos en Auth0 |
💡 Consejo: Keycloak no reemplaza necesariamente a los proveedores cloud en todos los escenarios. Si tu empresa ya está en el ecosistema Azure y necesita integración nativa con Microsoft 365, Teams y Entra ID, Azure Entra sigue siendo la mejor opción. Keycloak brilla cuando necesitas control total, costo previsible (cero) e independencia del vendor.
Principales Funcionalidades
Keycloak incluye funcionalidades que los proveedores cloud cobran por separado:
- Single Sign-On (SSO) — login único entre múltiples aplicaciones
- Identity Brokering — federación con proveedores externos (Google, GitHub, Facebook, Azure AD, SAML)
- User Federation — integración con LDAP y Active Directory
- Fine-grained Authorization — políticas de autorización basadas en roles, groups, scopes y resources
- Multi-Factor Authentication (MFA) — TOTP, WebAuthn/FIDO2, SMS, email
- Account Management Console — portal self-service para que el usuario gestione su perfil, sesiones y 2FA
- Admin Console — panel web completo para gestionar realms, clients, users y roles
- Event Logging y Audit Trail — registro detallado de eventos de autenticación
- API REST para Administración — automatización completa vía API
- Extensibilidad vía SPI — Service Provider Interfaces para personalizaciones avanzadas
Requisitos Previos
- Docker Desktop o Podman instalado y funcionando
- .NET 8.0 SDK (o superior) instalado — descarga aquí
- VS Code o Visual Studio como IDE
- Conocimiento básico de OAuth2 y OpenID Connect
Keycloak en Contenedor: Setup Completo
Docker Compose para Desarrollo
La forma más rápida y recomendada de ejecutar Keycloak localmente es en un contenedor. Uso docker-compose con PostgreSQL como base de datos (la misma que usarías en producción):
| |
⚠️ Atención: El comando
start-devhabilita el modo de desarrollo con HTTP, caché local y hot-reload de temas. Nunca usesstart-deven producción — usastartcon HTTPS configurado y las variables de producción adecuadas.
Inicia el stack:
| |
Tras unos segundos, accede al panel admin en http://localhost:8180 con las credenciales admin / admin.
Configuración Inicial: Realm y Client
Keycloak organiza todo en Realms — cada realm es un espacio aislado con sus propios usuarios, clients, roles y configuraciones. El realm master está reservado para la administración del servidor. Creo un realm para la aplicación:
1. Crear un Realm
- En el panel admin, haz clic en el desplegable
masteren la esquina superior izquierda - Haz clic en Create Realm
- Completa: Realm name =
meu-app - Haz clic en Create
2. Crear un Client (para la API ASP.NET Core)
- En el realm
meu-app, ve a Clients → Create client - Completa:
- Client type: OpenID Connect
- Client ID:
minha-api
- En la siguiente pantalla:
- Client authentication: ON (confidential client)
- Authorization: ON (si quieres usar authorization services)
- En Valid Redirect URIs:
https://localhost:5001/*yhttp://localhost:5000/* - En Web Origins:
+(permite todos los origins de los redirect URIs) - Haz clic en Save
3. Obtener el Client Secret
- Después de guardar, ve a la pestaña Credentials
- Copia el Client secret — lo necesitarás en la configuración de la API
4. Crear un Usuario de Prueba
- Ve a Users → Add user
- Completa:
- Username:
usuario.teste - Email:
[email protected] - First Name:
Usuário - Last Name:
Teste - Email verified: ON
- Username:
- Haz clic en Create
- Ve a la pestaña Credentials → Set password
- Define una contraseña y desmarca Temporary
5. Crear Roles
- Ve a Realm roles → Create role
- Crea los roles:
admin,user,manager - Asigna roles al usuario: Users → selecciona el usuario → pestaña Role mapping → Assign role
ℹ️ Información: Todo lo que hice manualmente arriba puede automatizarse vía Keycloak Admin REST API o importando un realm en JSON — ideal para pipelines de CI/CD.
Visión General del Flujo de Autenticación
Antes de entrar en el código, mira cómo encajan las piezas. El diagrama siguiente muestra el flujo completo: el Browser se autentica vía OpenID Connect en Keycloak, recibe un JWT y lo envía como Bearer Token a la API ASP.NET Core, que valida el token consultando las claves públicas (JWKS) de Keycloak:
Integración con C# y ASP.NET Core
Los siguientes ejemplos usan C# con ASP.NET Core, pero el mismo flujo se aplica a cualquier lenguaje/framework. Keycloak se comunica mediante protocolos estándar (OIDC/OAuth2), así que la integración se reduce a configurar la validación de JWT Bearer en tu stack — algo que todas las plataformas modernas soportan de forma nativa o mediante una biblioteca:
| Lenguaje / Framework | Biblioteca / Recurso de Integración |
|---|---|
| C# / ASP.NET Core | Microsoft.AspNetCore.Authentication.JwtBearer (usado en este artículo) |
| Java / Spring Boot | Spring Security OAuth2 Resource Server — spring-boot-starter-oauth2-resource-server |
| Python / Django | django-allauth o mozilla-django-oidc |
| Python / FastAPI | python-jose + validación manual de JWT o fastapi-keycloak |
| Node.js / Express | keycloak-connect (adaptador oficial) o jsonwebtoken + JWKS |
| Node.js / NestJS | nest-keycloak-connect |
| Go | go-oidc (CoreOS) |
| PHP / Laravel | socialiteproviders/keycloak o robsontenorio/laravel-keycloak-guard |
| Ruby on Rails | omniauth-keycloak |
| Angular / React / Vue | keycloak-js (adaptador oficial para SPAs) |
ℹ️ Información: Keycloak también ofrece adaptadores oficiales para varias plataformas. Sin embargo, para nuevas integraciones se recomienda usar bibliotecas genéricas de OIDC/JWT de tu lenguaje — así no quedas acoplado a un adaptador específico de Keycloak.
Configuración de la API
Creo una API REST protegida por Keycloak usando ASP.NET Core 8 con autenticación OpenID Connect / JWT Bearer:
| |
Configura el appsettings.json con los datos de Keycloak:
| |
⚠️ Atención: En producción,
RequireHttpsMetadatadebe sertruey elClientSecretdebe venir de variables de entorno o de Azure Key Vault, nunca hardcoded en elappsettings.json.
Program.cs — Configuración Completa
| |
💡 Consejo: Keycloak almacena los roles del realm dentro de un claim llamado
realm_accessen el JWT. El código anterior extrae esos roles y los mapea aClaimTypes.Rolede .NET, lo que permite usar[Authorize(Roles = "admin")]con normalidad. Sin ese mapeo,User.IsInRole("admin")no funciona.
Controller Protegido
Crea un controller que demuestre los distintos niveles de acceso:
| |
Obteniendo un Token para Pruebas
Para probar la API, necesitas obtener un token de Keycloak. Usa el flujo Resource Owner Password (solo para pruebas/desarrollo):
| |
La respuesta contendrá el access_token. Úsalo para llamar a la API:
| |
Salida esperada:
| |
Service para Comunicarse con la Admin API
Para escenarios en los que tu aplicación necesita gestionar usuarios, roles o sesiones de forma programática, Keycloak expone una Admin REST API completa. Así se crea un servicio para consumir esa API:
| |
Regístralo en el Program.cs:
| |
ℹ️ Información: Para que el client
minha-apipueda acceder a la Admin API, es necesario habilitar la Service Account del client en Keycloak y asignar el rolrealm-management→realm-admina la service account.
Implementando el Logout
El logout en una integración con Keycloak va más allá de simplemente descartar el token del lado del cliente. Para que la sesión quede completamente cerrada, hay que notificar a Keycloak para que también invalide la sesión en el servidor de identidad — esto se llama RP-Initiated Logout (especificación OpenID Connect).
Keycloak expone el endpoint de logout en:
| |
Logout vía API (Back-Channel)
Para invalidar la sesión del usuario directamente desde tu API, usa el refresh_token o el id_token_hint:
| |
Registra el IHttpClientFactory en el Program.cs (si aún no está registrado):
| |
Probando el Logout
1. Obtén un token (incluido el refresh_token):
| |
💡 Consejo: El scope
offline_accessgarantiza que Keycloak devuelva unrefresh_tokenen la respuesta. Sin él, según la configuración del client, puede que el refresh token no se emita.
2. Realiza el logout vía API:
| |
3. U obtén la URL de logout para redirección (front-channel):
| |
Logout en el Front-End (SPA)
En aplicaciones front-end (Angular, React, Vue), el logout normalmente se hace mediante redirección al endpoint de Keycloak:
| |
Si usas el adaptador oficial keycloak-js, el logout es aún más simple:
| |
⚠️ Atención: Para que
post_logout_redirect_urifuncione, la URL de redirección debe estar registrada en las Valid Post Logout Redirect URIs del client en Keycloak. En desarrollo, agregahttp://localhost:*. En producción, usa solo las URLs exactas de tu dominio.
Personalización de la Pantalla de Login
Una de las grandes ventajas de Keycloak frente a los proveedores cloud es la libertad total para personalizar la pantalla de login. Puedes cambiar el logo, los colores, las fuentes y los textos, e incluso crear temas completamente desde cero usando plantillas FreeMarker.
Estructura de un Tema de Keycloak
Keycloak usa un sistema de temas basado en FreeMarker Templates. Cada tema puede sobrescribir parcialmente el tema por defecto (keycloak o keycloak.v2):
| |
Creando el Tema Personalizado
1. Archivo theme.properties
| |
2. CSS Personalizado (resources/css/login.css)
| |
3. Mensajes en Portugués (messages/messages_pt_BR.properties)
| |
Montando el Tema en el Contenedor
Agrega el volumen del tema en el docker-compose.keycloak.yml:
| |
Como alternativa, activa el tema desde el panel admin:
- Ve a Realm Settings → pestaña Themes
- En Login theme, selecciona
meu-tema - Haz clic en Save
💡 Consejo: En el modo
start-dev, Keycloak hace hot-reload de los temas automáticamente. Basta con guardar el archivo CSS o la plantilla FreeMarker y recargar la página de login para ver los cambios al instante — sin reiniciar el contenedor.
Resultado Visual
Después de aplicar el tema, la pantalla de login tendrá:
- ✅ El logo de tu empresa en la parte superior
- ✅ Colores personalizados en botones y campos
- ✅ Textos en portugués de Brasil
- ✅ Card de login con bordes redondeados y sombra suave
- ✅ Background con degradado personalizado
- ✅ Favicon personalizado
📝 Ejemplo: Empresas como Red Hat, Siemens y Deutsche Telekom usan Keycloak con temas totalmente personalizados que no se distinguen de soluciones SaaS propietarias. El usuario final nunca percibe que está usando un identity provider open-source.
Keycloak en Producción con Contenedores
Docker Compose para Producción
En producción, las diferencias respecto al setup de desarrollo son:
| |
⚠️ Atención: En producción, considera usar
builden lugar de volúmenes para el tema. La imagen oficial soporta multi-stage build conkc.sh buildpara optimizar el arranque:
| |
Consejos de Producción — Seguridad y Rendimiento
Proxy reverso con Nginx:
Si Keycloak está detrás de un Nginx (como en la arquitectura descrita en el patrón BFF), configura el location para proxy reverso:
| |
Consejos y Buenas Prácticas
Separa el realm de producción del de administración — nunca uses el realm
masterpara tus usuarios. Crea realms específicos por aplicación o dominio de negocio.Exporta y versiona la configuración del realm — usa el endpoint de exportación de Keycloak (
/admin/realms/{realm}/export) para guardar la configuración como JSON y versionarla en Git. Así puedes recrear todo el entorno a partir del código (Infrastructure as Code).Habilita rate limiting en el proxy reverso — Keycloak gestiona la autenticación, blanco frecuente de ataques de fuerza bruta. Configura
limit_reqen Nginx para restringir las solicitudes al endpoint de login.Configura correctamente la caché de Infinispan — en producción con múltiples instancias (cluster), Keycloak usa Infinispan como caché distribuida de sesiones. Consulta la documentación oficial de caching para escenarios de alta disponibilidad.
Monitorea con health checks y métricas — habilita
KC_HEALTH_ENABLEDyKC_METRICS_ENABLEDpara exponer los endpoints/healthy/metrics(compatibles con Prometheus).Usa
start --optimizeden producción — el comandostartcon el flag--optimizedprecompila la configuración y reduce drásticamente el tiempo de arranque (de ~30s a ~5s).Actualiza con regularidad — Keycloak recibe actualizaciones de seguridad frecuentes. Sigue el blog oficial y prueba las nuevas versiones en staging antes de actualizar producción.
Haz backup de la base de datos con regularidad — el PostgreSQL de Keycloak contiene todos los datos de identidad. Un
pg_dumpprogramado es obligatorio en cualquier entorno de producción.
Comparativa: Cuándo Usar Keycloak vs Cloud
| Escenario | Recomendación |
|---|---|
| Startup con presupuesto limitado | ✅ Keycloak — costo cero, todas las features |
| Empresa ya en el ecosistema Microsoft 365 | ⚡ Azure Entra ID — integración nativa |
| Aplicación 100% AWS con Serverless | ⚡ AWS Cognito — integración con Lambda/API Gateway |
| Requisito de soberanía de datos (LGPD, GDPR) | ✅ Keycloak — los datos quedan en tu infra |
| Equipo sin experiencia en infra/contenedores | ⚡ Auth0 o Firebase Auth — SaaS gestionado |
| Escenario on-premises o air-gapped | ✅ Keycloak — única opción viable |
| Necesidad de personalización total de la UX | ✅ Keycloak — temas FreeMarker ilimitados |
| Alta escala (millones de MAU) | 🤔 Depende — Keycloak escala, pero exige experiencia en cluster |
ℹ️ Información: Nada impide un uso híbrido. Muchas empresas usan Keycloak como identity broker federando con Azure AD/Google Workspace. Así, los empleados inician sesión con el SSO corporativo (Azure AD), pero los datos de sesión y autorización quedan centralizados en Keycloak.
Conclusión
Keycloak es una de las herramientas más subestimadas del ecosistema open-source. Entrega, gratis, funcionalidades por las que los proveedores cloud cobran cientos o miles de dólares al mes: SSO, MFA, identity brokering, user federation, personalización completa de la UI y una potente API REST para automatización. Ejecutarlo en contenedor con Docker o Podman es trivial, y la integración vía OpenID Connect es directa — en este artículo lo demostré con ASP.NET Core y C#, pero el mismo flujo funciona con Java, Python, Node.js, Go, PHP, Ruby y cualquier otra tecnología que soporte JWT y OIDC. Keycloak es un servidor de identidad agnóstico de lenguaje: la capa de autenticación corre en el contenedor y tu aplicación solo valida tokens estándar.
Si trabajas en un escenario donde el costo importa, donde la soberanía de los datos es un requisito, o simplemente quieres control total sobre la autenticación y la autorización de tu aplicación — sin importar el lenguaje o el framework —, Keycloak merece un lugar destacado en tu stack. Empieza en pequeño, en un entorno de desarrollo con Docker Compose, valida el flujo con tu aplicación, personaliza la pantalla de login con la identidad visual de tu marca y, cuando tengas confianza, llévalo a producción con HTTPS, proxy reverso y backups.
La autenticación es la puerta de entrada de tu sistema — y con Keycloak, esa puerta es gratuita, segura y completamente tuya.
Lee También
- Autenticación y Autorización: JWT, OAuth2 y OpenID Connect — fundamentos de los protocolos que implementa Keycloak
- BFF Backend For Frontend: Seguridad en SPAs — patrón arquitectónico que combina perfectamente con Keycloak como identity provider
Referencias
- Keycloak — Sitio Oficial — documentación, descargas y guía de inicio rápido
- Keycloak Server Administration Guide — guía completa de administración del servidor
- Keycloak Docker Image — Quay.io — imagen oficial del contenedor
- Keycloak Admin REST API — referencia completa de la API de administración
- Keycloak Themes Documentation — guía de personalización de temas
- Microsoft — JWT Bearer Authentication in ASP.NET Core — documentación oficial de .NET para autenticación JWT
- CNCF — Keycloak Project — página del proyecto en la Cloud Native Computing Foundation
- Repositorio blog-zocateli-sample — Keycloak — Código fuente completo de los ejemplos de este artículo

Al comentar, aceptas nuestra Política de Privacidad, Términos de Uso, Política de Eliminación de Datos.