Administración de Keycloak¶
La Admin Console de Keycloak es la interfaz central para gestionar realms, clientes, usuarios, roles y políticas de seguridad. En producción el acceso a la consola debe restringirse a la red privada del VPS.
Acceso a la consola¶
URL (producción): https://auth.example.com/admin/
URL (local): http://localhost:8080/admin/
Credenciales iniciales: definidas en KC_ADMIN y KC_ADMIN_PASSWORD (.env)
Cambiar las credenciales por defecto inmediatamente
Las credenciales del administrador inicial se definen en variables de entorno. Cambia la contraseña del admin en la primera sesión y asegúrate de que el usuario admin del realm master solo es accesible desde la red interna.
Estructura de la consola¶
| Sección | Descripción |
|---|---|
| Realm Settings | Configuración general: tokens TTL, brute force, sesiones, email, themes |
| Clients | Clientes OAuth2/OIDC registrados en el realm |
| Client Scopes | Scopes compartidos entre clientes; mappers de claims |
| Realm Roles | Roles a nivel de realm asignables a usuarios |
| Users | Gestión de usuarios: crear, editar, asignar roles, credenciales |
| Groups | Grupos de usuarios para asignación masiva de roles |
| Identity Providers | Configuración de IdPs externos (LDAP, Google, Azure AD) |
| Authentication | Flujos de autenticación personalizables (MFA, passwordless) |
| Events | Logs de eventos de login, error y admin |
| Sessions | Sesiones activas por usuario o cliente |
Configuración recomendada por realm¶
Tokens y sesiones¶
Realm Settings → Tokens:
Access Token Lifespan: 5 minutos (300s)
Access Token Lifespan For Implicit Flow: deshabilitado
Client Session Idle: 30 minutos
Client Session Max: 8 horas
Refresh Token Max Reuse: 0 (cada uso invalida el anterior)
SSO Session Idle: 30 minutos
SSO Session Max: 10 horas
Brute Force Protection¶
Realm Settings → Security Defenses → Brute Force Detection:
Enabled: ✅
Permanent Lockout: ❌
Max Login Failures: 5
Wait Increment: 60 segundos
Max Wait: 900 segundos
Failure Reset Time: 12 horas
Password Policy¶
Authentication → Password Policy:
Minimum Length: 12
Uppercase Characters: 1
Lowercase Characters: 1
Special Characters: 1
Not Username: ✅
Password History: 5
Maximum Age: 90 días
Admin CLI (kcadm.sh)¶
La Admin CLI permite gestionar Keycloak de forma programática desde la terminal o scripts.
# Autenticarse (una vez por sesión)
KC_URL="http://localhost:8080"
/opt/keycloak/bin/kcadm.sh config credentials \
--server $KC_URL \
--realm master \
--user admin \
--password $KC_ADMIN_PASSWORD
# Crear un realm
/opt/keycloak/bin/kcadm.sh create realms \
-s realm=realm-internal \
-s enabled=true \
-s displayName="Internal Realm"
# Crear un cliente
/opt/keycloak/bin/kcadm.sh create clients \
-r realm-internal \
-s clientId=mi-app \
-s publicClient=true \
-s "redirectUris=[\"https://app.example.com/callback\"]" \
-s standardFlowEnabled=true
# Listar usuarios
/opt/keycloak/bin/kcadm.sh get users -r realm-internal
# Crear un usuario
/opt/keycloak/bin/kcadm.sh create users \
-r realm-internal \
-s username=juan.perez \
-s email=juan.perez@example.com \
-s firstName=Juan \
-s lastName=Pérez \
-s enabled=true
# Asignar rol a usuario
/opt/keycloak/bin/kcadm.sh add-roles \
-r realm-internal \
--uusername juan.perez \
--rolename admin
# Configurar brute force
/opt/keycloak/bin/kcadm.sh update realms/realm-internal \
-s bruteForceProtected=true \
-s failureFactor=5 \
-s waitIncrementSeconds=60 \
-s maxFailureWaitSeconds=900
Admin REST API¶
Keycloak expone una REST API completa para automatización.
# Obtener token admin
ADMIN_TOKEN=$(curl -s -X POST \
"http://localhost:8080/realms/master/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password" \
-d "client_id=admin-cli" \
-d "username=admin" \
-d "password=${KC_ADMIN_PASSWORD}" | jq -r '.access_token')
# Listar realms
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:8080/admin/realms" | jq '.[].realm'
# Obtener estadísticas de un realm
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:8080/admin/realms/realm-internal/users/count"
# Ver eventos recientes
curl -s -H "Authorization: Bearer $ADMIN_TOKEN" \
"http://localhost:8080/admin/realms/realm-internal/events?max=20" | jq .
Gestión de eventos y auditoría¶
Admin Console → Realm Settings → Events:
Save Events: ✅
Saved Types: LOGIN, LOGIN_ERROR, LOGOUT, CLIENT_LOGIN, CLIENT_LOGIN_ERROR,
REFRESH_TOKEN, REFRESH_TOKEN_ERROR, REGISTER, REGISTER_ERROR
Expiration: 30 días
Save Admin Events: ✅
Include Representation: ✅ (guarda el JSON del recurso modificado)
Exportar eventos a un sistema externo
Para auditoría en producción, configura un Event Listener que envíe eventos a Kafka o a un endpoint HTTP. Keycloak incluye el listener jboss-logging por defecto; existen listeners de la comunidad para enviar eventos a sistemas externos.
Seguridad de la Admin Console¶
# compose.yml — Traefik labels para Keycloak
labels:
# Exponer /realms y /resources públicamente
- "traefik.http.routers.keycloak.rule=Host(`auth.example.com`) && (PathPrefix(`/realms`) || PathPrefix(`/resources`))"
# Bloquear /admin desde internet (solo acceso por VPN/SSH tunnel)
- "traefik.http.routers.keycloak-admin.rule=Host(`auth.example.com`) && PathPrefix(`/admin`)"
- "traefik.http.routers.keycloak-admin.middlewares=ip-whitelist@file"