Qué es Keycloak: SSO, OAuth 2.0 y gestión de cuentas de código abierto

Qué es Keycloak

Keycloak — un servidor de identidad de código abierto: se encarga del inicio de sesión de los usuarios, el almacenamiento de cuentas y la emisión de permisos para tus aplicaciones. Se utiliza para no implementar la autorización en cada servicio por separado: el usuario inicia sesión una vez (SSO), y las aplicaciones reciben la confirmación de Keycloak mediante los protocolos estándar OpenID Connect, OAuth 2.0 o SAML 2.0.

El proyecto se distribuye bajo la licencia Apache 2.0, funciona sobre la plataforma Quarkus y forma parte de la Cloud Native Computing Foundation como proyecto en incubación. La versión vigente en septiembre de 2026 es la 26.7.4.

Qué puede hacer

• Inicio de sesión único (SSO). El usuario inicia sesión una vez y obtiene acceso a todas las aplicaciones conectadas; el cierre de sesión también puede ser global.
• Protocolos estándar. OpenID Connect y OAuth 2.0 para aplicaciones web y móviles y APIs, SAML 2.0 para sistemas empresariales que no soportan OIDC.
• Autenticación multifactor. Códigos de un solo uso desde una aplicación autenticadora (TOTP), llaves hardware y llaves de dispositivo según el estándar WebAuthn.
• Acceso mediante proveedores externos. Google, GitHub, un proveedor SAML u OIDC corporativo, así como Active Directory y LDAP — Keycloak puede tomar usuarios desde un directorio existente sin migrarlos.
• Roles y grupos. Los permisos se definen a nivel de realm y de clientes individuales y se pasan a la aplicación en el token.
• Extensibilidad. Temas de personalización de las páginas de inicio de sesión y proveedores propios mediante Service Provider Interfaces (SPI).

Conceptos básicos

• Realm — un espacio aislado con sus propios usuarios, clientes y configuraciones. El realm de servicio master está destinado solo para administración; para las aplicaciones se crea un realm separado.
• Client — una aplicación que confía en Keycloak para el inicio de sesión de usuarios. Para una aplicación web con servidor se usa un client confidencial con secreto, para una aplicación de una sola página y móvil — un client público con PKCE.
• Roles existen a nivel realm (comunes) y a nivel de cliente (para una aplicación concreta). Es más cómodo asignar roles a grupos que a usuarios individuales.

Cómo arrancar

Para familiarizarse basta con un comando del manual oficial — arranca Keycloak en modo desarrollo con una cuenta de administrador:

docker run -p 127.0.0.1:8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.7.4 start-dev

El modo start-dev no sirve para producción: guarda los datos en la base integrada dev-file, que según la documentación está pensada solo para desarrollo, y no requiere HTTPS. Para una instalación en producción se necesitan:

• base de datos externa — PostgreSQL, MySQL, MariaDB, Oracle o Microsoft SQL Server (parámetros --db, --db-url-host, --db-username, --db-password);
• dirección del servidor — en modo producción es obligatorio el parámetro --hostname (mejor como URL completa) o explícitamente --hostname-strict false;
• TLS — certificado y clave en formato PEM (--https-certificate-file, --https-certificate-key-file) o terminación TLS en un proxy inverso; en este segundo caso se necesitan --http-enabled=true y --proxy-headers xforwarded (o forwarded).

Ejemplo de arranque detrás de un proxy inverso que termina TLS:

bin/kc.sh start \
  --hostname https://sso.example.ru \
  --db postgres --db-url-host db.internal \
  --db-username keycloak --db-password 'длинный-пароль' \
  --http-enabled=true --proxy-headers xforwarded

La documentación recomienda exponer al exterior solo las rutas /realms/, /resources/ y /.well-known/, y mantener la consola de administración /admin/, el realm de servicio /realms/master/, así como /metrics y /health accesibles solo desde la red interna.

Limitaciones

• Administración. Keycloak es otro servicio crítico: necesita actualizaciones (las nuevas versiones salen con frecuencia), copias de seguridad junto con la base de datos y supervisión. Si no está disponible, los usuarios no pueden iniciar sesión en ninguna aplicación.
• Recursos. Es una aplicación Java: necesita más memoria que servidores de autenticación ligeros y en el VPS más barato funcionará con dificultad.
• Barreras de entrada. Hay muchas configuraciones y algunas no son evidentes: tiempos de vida de tokens y sesiones, tipos de clientes, redirect URI, mapeo de atributos al conectar LDAP.

Errores típicos

• Instalación en producción en modo start-dev con la base integrada.
• Aplicaciones en el realm master y la consola de administración abierta a Internet.
• Redirect URI con asterisco (https://example.ru/* o simplemente *) — esto permite redirigir el token a una página ajena.
• Falta de copia de seguridad de la base de Keycloak: si se pierde, desaparecen todos los usuarios, clientes y configuraciones.
• Actualizar varias versiones de golpe sin leer las notas de migración.

Cuándo elegirlo

Keycloak es adecuado si la empresa tiene varias aplicaciones internas o de clientes, se necesita inicio de sesión único, autenticación de dos factores y conexión con Active Directory o LDAP, y los datos de los usuarios deben permanecer en servidores propios — incluyendo en Rusia, donde desde el 1 de julio de 2025 la recopilación primaria de datos personales de ciudadanos solo está permitida en bases de datos ubicadas en el territorio del país. Para un sitio pequeño con acceso mediante redes sociales es excesivo.

Si necesitas ayuda con la instalación y la conexión de aplicaciones, mira el servicio de configuración de Keycloak y SSO.