TL;DR — Resumen Rápido

Guía completa de Keycloak: instalación con Docker, configuración de realms, clientes OpenID Connect y SAML, federación LDAP, RBAC y alta disponibilidad.

Keycloak es la solución líder de código abierto para Gestión de Identidades y Accesos (IAM) — proporciona Inicio de Sesión Único (SSO), MFA, login social, federación LDAP/Active Directory y autorización detallada usando OpenID Connect, OAuth 2.0 y SAML 2.0. Esta guía cubre desde la instalación con Docker Compose hasta configuración de realms, RBAC, federación de identidades y clustering de alta disponibilidad.

Requisitos Previos

  • Docker 25+ y Docker Compose v2 (o un clúster Kubernetes para instalación con operator).
  • PostgreSQL 15+ para producción (H2 integrado es solo para desarrollo).
  • Proxy inverso (Nginx o Traefik) para terminación TLS en producción.
  • Familiaridad básica con conceptos de OAuth 2.0.

Arquitectura de Keycloak

Keycloak organiza todo en realms — dominios de seguridad aislados:

ConceptoDescripción
RealmTenant aislado. Contiene usuarios, clientes, roles y grupos
ClienteAplicación registrada para usar Keycloak
UsuarioIdentidad dentro del realm (local o federada)
RolEtiqueta de permiso. Roles de realm o roles de cliente
GrupoColección de usuarios con roles heredados
Proveedor de IdentidadIdP externo (Google, GitHub, SAML, LDAP)
Flujo de AutenticaciónPipeline configurable: login, OTP, WebAuthn

El realm master es el super-admin — úselo solo para administrar otros realms, nunca para usuarios de aplicaciones.

Paso 1: Instalar Keycloak con Docker Compose

version: "3.9"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: changeme
      KC_HOSTNAME: auth.ejemplo.com
      KC_PROXY: edge
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: adminpass
    ports:
      - "8080:8080"
    depends_on:
      - postgres

volumes:
  postgres_data:
docker compose up -d
# Acceda a la Consola de Administración en http://localhost:8080

Paso 2: Configuración del Realm

ConfiguraciónValor recomendado
Nombre visibleNombre de su marca
Tema de loginkeycloak o personalizado
Requerir SSLexternal requests (producción)
Tiempo inactivo SSO30 minutos
Duración del token de acceso5 minutos

Configure SMTP en Configuración del Realm → Email para correos de restablecimiento de contraseña.

Paso 3: Configuración de Clientes OpenID Connect

Clientes → Crear cliente:

  • Tipo de cliente: OpenID Connect
  • Client ID: myapp-client
  • Autenticación de cliente: Activada (confidencial) para apps de servidor; Desactivada (público) para SPAs
  • URIs de redirección válidas: https://myapp.ejemplo.com/callback
  • Web origins: https://myapp.ejemplo.com

Clientes Confidenciales vs Públicos

CaracterísticaConfidencialPúblico
Tiene secretoSíNo
Caso de usoServidor (Node, .NET, Python)SPA, app móvil
Flujo de código authCon secretoCon PKCE

Paso 4: Control de Acceso Basado en Roles (RBAC)

# Crear rol de realm con kcadm.sh
kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin --password adminpass

kcadm.sh create roles -r myapp -s name=app-admin
kcadm.sh create roles -r myapp -s name=app-user

Flujo recomendado: Roles → Grupos → Usuarios. Asigne roles a grupos y agregue usuarios a los grupos — evite asignar roles directamente a usuarios.

Los roles compuestos agrupan otros roles: cree superusuario y agréguele app-admin y app-user como composites.

Paso 5: Federación de Identidades

Login Social (Google, GitHub, Microsoft)

Proveedores de Identidad → Agregar proveedor → Google:

  1. Cree una app OAuth 2.0 en Google Cloud Console.
  2. Ingrese Client ID y Client Secret de Google en Keycloak.
  3. URI de redirección: https://auth.ejemplo.com/realms/myapp/broker/google/endpoint.

Federación LDAP / Active Directory

ConfiguraciónValor
ProveedorActive Directory
URL de conexiónldap://ad.corp.ejemplo.com
DN de bindCN=svc-keycloak,OU=CuentasServicio,DC=corp,DC=ejemplo,DC=com
DN de usuariosOU=Usuarios,DC=corp,DC=ejemplo,DC=com
Modo de sincronizaciónFORCE

Ejecute Sincronizar todos los usuarios para importar usuarios de AD.

Paso 6: Flujos de Autenticación y MFA

TOTP y WebAuthn

Para TOTP: Autenticación → Flujos → browser → Duplicar → Agregar Formulario OTP como REQUERIDO.

Para WebAuthn/Passkeys (Keycloak 22+):

  1. Autenticación → Políticas → Política WebAuthn — configure el dominio como Relying Party ID.
  2. Agregue Autenticador WebAuthn al flujo de navegador.

Alta Disponibilidad

environment:
  KC_CACHE: ispn
  KC_CACHE_STACK: jdbc-ping
  KC_DB: postgres
  KC_DB_URL: jdbc:postgresql://pgpool/keycloak
  • Habilite sesiones sticky en el balanceador (cookie AUTH_SESSION_ID).
  • Punto de salud: GET /health/ready.

Keycloak vs Alternativas

CaracterísticaKeycloakAuthentikAutheliaAuth0OktaFusionAuth
Código abiertoSíSíSíNoNoParcial
Auto-alojadoSíSíSíNoNoSí
SAML 2.0SíSíNoSíSíSí
Federación LDAPSíSíNoSíSíSí
Autorización detalladaSí (UMA)NoNoSí (pago)Sí (pago)Parcial
ComplejidadAltaMediaBajaBajaBajaMedia

Solución de Problemas

ProblemaSolución
”Invalid redirect_uri”Verifique URIs de redirección válidas — coincidencia exacta
”Client secret not valid”Regenere el secreto en Clientes → Credenciales
Bucle de loginVerifique que KC_HOSTNAME coincida con la URL real
Email no enviadoRevise SMTP en Configuración del Realm → Email
Usuarios LDAP no sincronizadosVerifique credenciales de bind y ejecute sincronización manual

Resumen

  • Los realms aíslan tenants — use siempre un realm dedicado para aplicaciones.
  • Los clientes confidenciales usan secretos; los públicos usan PKCE.
  • Los grupos con roles escalan el RBAC — evite asignar roles directamente a usuarios.
  • La sincronización LDAP con modo FORCE mantiene AD como fuente autoritativa.
  • Use KC_CACHE=ispn con jdbc-ping para HA sin dependencias adicionales.

Artículos Relacionados