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:

Concepto Descripción
Realm Tenant aislado. Contiene usuarios, clientes, roles y grupos
Cliente Aplicación registrada para usar Keycloak
Usuario Identidad dentro del realm (local o federada)
Rol Etiqueta de permiso. Roles de realm o roles de cliente
Grupo Colección de usuarios con roles heredados
Proveedor de Identidad IdP externo (Google, GitHub, SAML, LDAP)
Flujo de Autenticación Pipeline 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ón Valor recomendado
Nombre visible Nombre de su marca
Tema de login keycloak o personalizado
Requerir SSL external requests (producción)
Tiempo inactivo SSO 30 minutos
Duración del token de acceso 5 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ística Confidencial Público
Tiene secreto Sí No
Caso de uso Servidor (Node, .NET, Python) SPA, app móvil
Flujo de código auth Con secreto Con 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ón Valor
Proveedor Active Directory
URL de conexión ldap://ad.corp.ejemplo.com
DN de bind CN=svc-keycloak,OU=CuentasServicio,DC=corp,DC=ejemplo,DC=com
DN de usuarios OU=Usuarios,DC=corp,DC=ejemplo,DC=com
Modo de sincronización FORCE

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ística Keycloak Authentik Authelia Auth0 Okta FusionAuth
Código abierto Sí Sí Sí No No Parcial
Auto-alojado Sí Sí Sí No No Sí
SAML 2.0 Sí Sí No Sí Sí Sí
Federación LDAP Sí Sí No Sí Sí Sí
Autorización detallada Sí (UMA) No No Sí (pago) Sí (pago) Parcial
Complejidad Alta Media Baja Baja Baja Media

Solución de Problemas

Problema Solució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 login Verifique que KC_HOSTNAME coincida con la URL real
Email no enviado Revise SMTP en Configuración del Realm → Email
Usuarios LDAP no sincronizados Verifique 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