Qué es Keycloak y cómo se instala paso a paso

En casi cualquier aplicación moderna que uses a diario (correo, redes sociales, intranets corporativas, paneles de clientes, etc.) hay por detrás un sistema que decide quién eres y a qué puedes entrar. Cuando las empresas empiezan a acumular aplicaciones, servicios y APIs, gestionar usuarios, contraseñas, permisos y sesiones a mano se vuelve un auténtico dolor de cabeza.

Keycloak aparece justo para resolver ese embrollo: es una plataforma de gestión de identidades y accesos que centraliza la autenticación, la autorización y el inicio de sesión único para múltiples aplicaciones. En lugar de que cada desarrollo implemente su propio sistema de login, roles y recuperación de contraseñas, Keycloak se ocupa de todo eso y las aplicaciones simplemente confían en él mediante estándares como OAuth 2.0, OpenID Connect o SAML 2.0.

¿Qué es Keycloak y qué papel juega en la seguridad IAM?

Keycloak es un IdP (Identity Provider) open source, escrito en Java y mantenido por Red Hat (antes JBoss), con licencia Apache 2.0, por lo que se puede usar y adaptar libremente incluso en entornos comerciales. Existe una variante de pago y con soporte empresarial llamada Red Hat Single Sign-On, pero el núcleo funcional es el mismo.

Este servidor de identidades proporciona SSO, federación y multi‑tenancy: permite que un usuario inicie sesión una vez y pueda acceder a varias aplicaciones, que dichas aplicaciones deleguen la autenticación en Keycloak y que la gestión de usuarios, grupos, atributos y permisos se haga de forma centralizada, sin reimplementar la rueda en cada proyecto.

Keycloak destaca frente a otras soluciones IAM (gratuitas, open source o propietarias) por su madurez, adopción y compatibilidad con protocolos estándar. Aun así, la solución adecuada para cada organización dependerá de sus necesidades (soporte comercial, SLA, funcionalidades específicas, despliegue on‑premise frente a SaaS, etc.).

Uno de los puntos fuertes de Keycloak es que combina varias piezas: autenticación basada en OAuth 2.0 y OpenID Connect, soporte SAML 2.0, login social (Google, Facebook, GitHub, etc.), integración con LDAP y Active Directory, administración vía consola web, CLI y API REST, así como un modelo flexible de usuarios, grupos y roles que se reflejan en los tokens emitidos para las aplicaciones.

Bases necesarias: OAuth 2.0, OpenID Connect y los JWT

Para entender bien qué hace Keycloak conviene tener claros tres conceptos: OAuth 2.0, OpenID Connect (OIDC) y los JSON Web Tokens (JWT). No hace falta convertirse en experto, pero sí conocer la idea general, porque todo gira alrededor de ellos.

OAuth 2.0 como marco de autorización

OAuth 2.0 es un framework estándar de autorización de APIs, utilizado por gigantes como Google, Facebook, Microsoft, GitHub o LinkedIn. Su función principal es permitir que una aplicación (cliente) acceda a recursos de un usuario en otra aplicación o API, con permiso explícito del usuario, sin compartir credenciales constantemente.

En lugar de mandar usuario y contraseña en cada petición, OAuth 2.0 introduce el concepto de access_token: un token de acceso de vida corta que se envía en las llamadas HTTP a la API y que esta valida. El IdP (Keycloak, por ejemplo) es quien emite ese token tras verificar la identidad del usuario y su consentimiento.

El estándar define varios flujos de autorización (grant types) para adaptar el proceso al tipo de cliente: aplicaciones backend seguras, SPAs en navegador, apps móviles, dispositivos limitados, comunicaciones máquina a máquina, etc. Cada flujo marca qué se intercambia en cada paso (códigos de autorización, tokens, credenciales, etc.).

Los cuatro roles fundamentales de OAuth 2.0 son:

• Resource Owner: normalmente el usuario cuyo dato se quiere consultar o modificar.
• Client: la aplicación (web, móvil, IoT, backend…) que quiere actuar en nombre del usuario.
• Resource Server: la API que expone los datos y valida los access_token.
• Authorization Server: el IdP (Keycloak) que autentica al usuario y emite tokens.

Además, OAuth 2.0 introduce el concepto de scopes, que definen el alcance del permiso que el usuario concede a la aplicación: leer correo, publicar en una red social, acceder a un perfil básico, etc. El token emitido codifica qué permisos se le han otorgado realmente al cliente.

OpenID Connect: capa de identidad sobre OAuth 2.0

OpenID Connect (OIDC) añade identidad a OAuth 2.0. Mientras OAuth habla de autorización (qué puede hacer una aplicación), OIDC se ocupa de identificar de forma estandarizada quién es el usuario autenticado y cómo obtener sus datos básicos.

OIDC define endpoints y metadatos bien conocidos, como el documento de descubrimiento publicado en la ruta /.well-known/openid-configuration donde el proveedor indica URLs de autorización, token, claves públicas, userinfo, etc. Esto permite que las aplicaciones se configuren de forma casi automática.

También proporciona el endpoint UserInfo, que sirve para recuperar información del usuario autenticado (nombre, email, etc.) usando un access_token válido. Es muy habitual en integraciones basadas en Keycloak leer estos datos tras el login para poblar perfiles de usuario en la aplicación.

Access_token y JSON Web Tokens (JWT)

En muchas implementaciones modernas el access_token es un JWT (JSON Web Token). Se trata de un estándar (RFC 7519) para representar claims (afirmaciones) como un JSON firmado digitalmente, en tres partes separadas por puntos: cabecera, payload y firma, todo ello codificado en Base64URL.

La cabecera indica información técnica del token (algoritmo de firma, tipo de token y, a menudo, el identificador de la clave usada, kid). El payload contiene los claims, como:

• exp: fecha de caducidad.
• iat: instante de emisión.
• iss: emisor, normalmente la URL del IdP.
• sub: identificador único del usuario.
• aud: audiencia a la que va dirigido el token.
• jti: identificador único del token.

La firma se genera con una clave privada o secreta, de forma que cualquier modificación del token rompe la firma y se detecta en la validación. La API obtiene la clave pública desde el IdP gracias a la propiedad jwks_uri del documento de descubrimiento, que apunta a un JSON con la lista de claves públicas y sus kid.

Keycloak permite además personalizar los tokens emitidos: se pueden añadir claims adicionales basados en atributos de usuario, grupos, roles, o incluso valores fijos. Esto se hace mediante mappers configurados por cliente o por client scope, lo que facilita que las APIs reciban exactamente la información que necesitan.

Arquitectura de Keycloak: Realms, usuarios, grupos y roles

Keycloak organiza su configuración en Realms, que son como “servidores de identidad virtuales” dentro de una única instalación. Otros proveedores llaman a algo similar tenant o directorio. Cada realm tiene sus propios usuarios, grupos, clientes, políticas y ajustes independientes.

Por defecto existe un realm especial llamado master, que debe reservarse para tareas administrativas globales, como crear y gestionar otros realms. El usuario administrador tiene capacidad para manejar varios realms desde la misma consola sin tener que iniciar sesión con cuentas distintas para cada uno.

Dentro de un realm se pueden definir usuarios locales, asignarles atributos personalizados, agruparlos y relacionarlos con roles. El modelo está muy pensado para que la información relevante acabe reflejada en los tokens que consume la aplicación (roles, grupos, datos de perfil, flags de seguridad, etc.).

Los grupos permiten organizar usuarios de forma jerárquica: un grupo puede tener subgrupos (hijos), y un usuario hereda los atributos y roles de todos los grupos de los que forma parte, incluidos los padres. Esto hace posible modelos de autorización muy flexibles sin tener que repetir configuraciones usuario a usuario.

En cuanto a roles, hay dos niveles principales:

• Roles de realm (realm roles): globales dentro del realm, se usan mucho para permisos transversales.
• Roles de cliente (client roles): específicos de una aplicación concreta, lo que permite granularidad fina para cada servicio.

Keycloak soporta composite roles, es decir, roles que a su vez incluyen otros roles. Esto ayuda a agrupar permisos y asignarlos de golpe a usuarios o grupos, aunque conviene no abusar para no complicar la gestión ni afectar al rendimiento.

Instalar Keycloak en modo desarrollo: Docker, Kubernetes y VM

Para montar un entorno de laboratorio con Keycloak hay varias opciones sencillas: contenedor Docker, despliegue en Kubernetes (por ejemplo con Minikube) o instalación clásica en una máquina virtual con Linux y OpenJDK.

Keycloak en Docker

La forma más rápida de arrancar Keycloak para hacer pruebas es ejecutar un contenedor con la imagen oficial, exponiendo el puerto 8080 y pasando el usuario y contraseña de administración por variables de entorno, arrancando en modo start-dev (sin HTTPS y con base de datos H2 embebida):

Con un solo comando Docker se obtiene un servidor funcional en http://localhost:8080, suficiente para trastear con la consola de administración, crear realms, usuarios, clientes y probar integraciones básicas.

Keycloak en Kubernetes con Minikube

Si ya trabajas con Kubernetes, puedes desplegar Keycloak fácilmente usando los manifiestos de ejemplo del repositorio oficial. Se crea un Deployment y un Service y, a continuación, se abre un túnel con Minikube para acceder al servicio desde tu máquina, normalmente de nuevo en el puerto 8080.

Este enfoque es ideal para simular entornos más cercanos a producción (con pods, servicios, configuración externa, etc.) y para experimentar con despliegues, escalado y upgrades controlados de Keycloak en clústeres K8s.

Keycloak en Ubuntu con OpenJDK y PostgreSQL (modo dev avanzado)

Otra posibilidad es montar Keycloak en una VM Ubuntu usando OpenJDK y una base de datos PostgreSQL local, con certificado autofirmado y hostname personalizado. Aunque sigue siendo un escenario de pruebas, se acerca más a una topología de producción.

Los pasos típicos incluyen:

• Actualizar el sistema operativo e instalar Java (por ejemplo, OpenJDK 11 o superior).
• Instalar PostgreSQL (idealmente en un servidor separado, aunque en laboratorio puede ir en la misma máquina).
• Crear un usuario y base de datos específicos para Keycloak y conceder los privilegios adecuados.
• Crear un usuario de sistema sin privilegios (p. ej. keycloak) para ejecutar el servicio.
• Descargar la distribución oficial de Keycloak, descomprimirla en /opt/keycloak y ajustar permisos.
• Generar un certificado X.509 autofirmado con openssl y configurarlo en keycloak.conf junto con los parámetros de conexión a PostgreSQL y el hostname deseado.
• Definir una unidad systemd para arrancar Keycloak en modo desarrollo al inicio del sistema, estableciendo las credenciales de administrador vía variables de entorno.

Una vez levantado el servicio, se accede normalmente por HTTPS en el puerto 8443 con el hostname configurado. Si se usa un certificado autofirmado, habrá que confiar en él en el navegador (importando la CA o el propio certificado en el almacén de certificados de confianza de la máquina).

Despliegues avanzados: alta disponibilidad, PostgreSQL y proxy inverso

Cuando pasamos de laboratorio a producción, la película cambia: hay que pensar en alta disponibilidad, persistencia robusta de datos, certificados válidos y, a menudo, un proxy inverso que centralice el acceso HTTPS y el balanceo de carga.

Un patrón bastante habitual es desplegar varios nodos de Keycloak detrás de un balanceador (por ejemplo Nginx) y usar una base de datos PostgreSQL en modo HA como backend de persistencia. El objetivo es que ni la capa de aplicación ni la de datos tengan puntos únicos de fallo.

En este tipo de arquitecturas se suelen seguir pasos como:

• Preparar servidores Linux (Debian/Ubuntu) actualizados e instalar dependencias: unzip, wget, openjdk, openssl, etc.
• Crear un usuario de sistema keycloak con home en /opt/keycloak y sin permisos de login interactivo privilegiado.
• Descargar la versión deseada de Keycloak, descomprimirla y asignar su propiedad al usuario dedicado.
• Crear en PostgreSQL una base de datos específica, usuario y privilegios adecuados, ajustando también el propietario del esquema y los permisos por defecto sobre tablas.
• Generar certificados autofirmados (o usar certificados de una CA interna) para los nodos de Keycloak y configurar HTTPS en el servidor de aplicaciones.
• Ajustar keycloak.conf para conectar a la VIP de PostgreSQL, definir puertos HTTP/HTTPS, certificados, parámetros de proxy, nombre de host, stack de clúster (por ejemplo UDP) y niveles de log.
• Definir un servicio systemd simple que arranque Keycloak con kc.sh start o kc.sh start --optimized, gestionando reinicios automáticos ante fallos.

Sobre la capa de publicación y balanceo suele desplegarse Nginx como proxy inverso HTTPS, con su propio certificado TLS y una configuración upstream que apunte a los nodos de Keycloak en sus puertos de backend (habitualmente 8080 si se termia TLS en Nginx).

Para eliminar puntos únicos de fallo en el balanceador, es frecuente configurar dos nodos Nginx en alta disponibilidad mediante Keepalived. Esta herramienta gestiona una IP virtual flotante (VIP) que se anuncia en uno de los servidores como maestro y, en caso de caída, pasa al nodo de respaldo, manteniendo la continuidad del servicio.

Configurar un Realm, usuarios y registro de aplicaciones (clientes)

Una vez tenemos Keycloak en marcha, el siguiente paso lógico es crear un realm para nuestros usuarios y aplicaciones, y a partir de ahí definir usuarios, grupos, roles y clientes (las aplicaciones que van a delegar la autenticación en Keycloak).

Desde la Admin Console se crea un nuevo realm indicando simplemente su nombre. A partir de ese momento, tendremos un espacio aislado con su propia configuración. Entre los primeros ajustes suele ser interesante:

• Configurar SMTP para envío de correos (verificación de email, recuperación de contraseña, notificaciones).
• Habilitar si se desea la Declarative User Profile, que permite definir de forma declarativa qué atributos tendrá un usuario, qué validaciones aplican y si son editables por el propio usuario.
• Ajustar parámetros de login: permitir o no autoregistro, recordar sesión entre reinicios de navegador, permitir recuperación de contraseña, etc.

Crear un usuario en un realm es tan simple como rellenar un formulario con nombre de usuario, email, nombre y apellidos. Después se establece su contraseña (temporal o no) desde la pestaña de credenciales. A partir de ahí, se le pueden asignar grupos, roles y atributos adicionales.

Keycloak ofrece una Account Console específica para usuarios finales, donde pueden ver y modificar sus datos de perfil, cambiar contraseña, revisar sesiones activas o gestionar factores de autenticación adicionales. Es una forma muy cómoda de delegar en el usuario parte de la administración básica de su cuenta.

La impersonación es otra funcionalidad interesante: un administrador con permiso puede “hacerse pasar” por un usuario desde la consola para reproducir problemas, verificar permisos, etc., sin necesitar la contraseña del usuario.

Para que una aplicación use Keycloak como IdP, hay que registrarla como cliente. En la sección Clients se crea un nuevo client ID, se indica que el tipo es OpenID Connect (salvo que se vaya a usar SAML) y se seleccionan los flujos OAuth 2.0 permitidos: Standard Flow (Authorization Code), Direct Access Grants (Password), Implicit, Client Credentials (service accounts), Device Code, CIBA, etc.

En la configuración del cliente también se decide si este requiere autenticación de cliente (client secret o certificados), qué URIs de redirección son válidas y qué orígenes web están permitidos (muy importante en SPAs por las políticas CORS). A partir de ahí, la aplicación puede usar librerías oficiales o de terceros para delegar la autenticación en Keycloak mediante OIDC.

Integración con directorios externos y otros proveedores de identidad

Keycloak puede funcionar como fuente de identidades local (usuarios, grupos y roles definidos dentro de su propia base de datos) o puede actuar como broker de identidad frente a uno o varios proveedores externos.

Una integración muy habitual es con Azure Active Directory: Azure AD almacena usuarios y grupos corporativos y Keycloak se conecta como cliente OIDC para descargar identidades y grupos, mapeándolos a usuarios y roles locales. De esta forma se evita duplicar identidades y tareas de administración en varios sitios.

A grandes rasgos, para usar Azure AD como IdP externo se hace lo siguiente:

• Registrar una aplicación en Azure AD, obteniendo su client ID y creando un client secret.
• Configurar en Azure AD las URIs de redirección hacia Keycloak (endpoint del broker OIDC en el realm correspondiente).
• Ajustar en la aplicación de Azure AD las claims que se emitirán en el token, por ejemplo incluyendo los grupos del usuario.
• En Keycloak, crear un Identity Provider de tipo OpenID Connect apuntando a los endpoints de Azure (authorization, token, logout, userinfo) y configurando client ID, client secret y los parámetros de login deseados.

Una vez establecida la confianza entre ambos, cuando un usuario inicia sesión a través de Azure AD, Keycloak crea (o sincroniza) el usuario localmente y puede mapear grupos de Azure a roles de Keycloak mediante mappers avanzados. Por ejemplo, el grupo “Desarrolladores” en Azure puede traducirse en el rol “Desarrolladores” en Keycloak, que luego se trasladará a las aplicaciones y servicios integrados (como Jenkins).

Además de Azure AD, Keycloak permite federar identidades con LDAP, Active Directory clásico, otros IdPs OIDC, proveedores sociales (Google, Facebook, GitHub, etc.) y más, pudiendo mezclar varios orígenes de forma simultánea dentro del mismo realm.

Seguridad adicional: bots, CAPTCHA y buenas prácticas

Aunque Keycloak fortalece mucho la seguridad en autenticación (MFA, políticas de contraseña, bloqueo de cuentas, control de sesiones, etc.), las páginas de login, registro y recuperación de contraseña siguen siendo objetivos claros de bots y ataques automatizados.

Para mitigar este tipo de amenazas, es recomendable combinar Keycloak con mecanismos anti‑bot como soluciones CAPTCHA conformes con GDPR, que distingan entre tráfico humano y automatizado sin arruinar la experiencia de usuario. Estas soluciones se integran normalmente en los formularios de login y registro, añadiendo una capa extra de defensa ante ataques de relleno de credenciales, creación masiva de cuentas o abuso de flujos de recuperación de contraseña.

Más allá del CAPTCHA, otras buenas prácticas incluyen monitorizar logs de acceso, establecer alertas ante picos anómalos de intentos fallidos, revisar periódicamente los tokens emitidos y su duración, asegurar que solo se exponen los endpoints necesarios al exterior y mantener Keycloak y sus dependencias actualizados con los últimos parches de seguridad.

Todo este ecosistema de funcionalidades (SSO, multi‑tenancy, integración con directorios externos, tokens configurables, despliegues en alta disponibilidad y protección frente a bots) convierte a Keycloak en una pieza muy potente para centralizar la autenticación y autorización de aplicaciones modernas, ayudando a las empresas a reforzar su postura de seguridad sin sacrificar la experiencia de usuario ni reinventar continuamente la gestión de identidades.