Instalación de Keycloak en

Qué configuramos y por qué

En el mundo moderno, donde cada aplicación requiere autenticación, la gestión de cuentas puede convertirse en un verdadero dolor de cabeza. Keycloak resuelve este problema al proporcionar una potente plataforma para la gestión de identidad y acceso (IAM) con soporte para inicio de sesión único (SSO).

Keycloak es una solución de código abierto que permite gestionar de forma centralizada usuarios, roles, grupos y proporcionarles acceso a sus aplicaciones. Soporta protocolos estándar como OpenID Connect, OAuth 2.0 y SAML 2.0, lo que lo hace compatible con prácticamente cualquier aplicación web o servicio moderno. Con Keycloak, puede:

• Implementar inicio de sesión único (SSO): Los usuarios solo necesitan autenticarse una vez para acceder a todas las aplicaciones conectadas sin volver a introducir sus credenciales.
• Gestionar usuarios y roles: Creación, edición y eliminación centralizada de usuarios, asignación de roles y grupos.
• Utilizar autenticación social: Integrar fácilmente el inicio de sesión a través de Google, GitHub, Facebook y otros proveedores populares.
• Aplicar autenticación multifactor (MFA): Aumentar la seguridad de las cuentas.
• Configurar federación de identidad: Conectar proveedores externos como LDAP o Active Directory.

En resumen, el lector obtendrá un servidor Keycloak completamente configurado y listo para usar, que servirá como punto central de autenticación para sus proyectos. Esto simplificará significativamente el desarrollo de nuevas aplicaciones, aumentará la seguridad y mejorará la experiencia del usuario.

Alternativas: Cloud-managed vs Self-hosted

Existen servicios comerciales de IAM/SSO en la nube, como Auth0, Okta, Amazon Cognito, Google Identity Platform. Ofrecen la comodidad de una solución "llave en mano", eliminando la carga de mantenimiento y escalado. Sin embargo, tienen sus desventajas:

• Costo: A medida que crece el número de usuarios o funciones, los costos pueden aumentar rápidamente.
• Control de datos: Sus datos de autenticación se almacenan en un proveedor externo, lo que puede ser inaceptable por razones de seguridad, privacidad o requisitos regulatorios.
• Flexibilidad: Aunque los servicios en la nube son flexibles, aún tienen limitaciones en cuanto a personalización e integración que pueden ser inherentes a una solución de código abierto.

Keycloak autoalojado en un VPS ofrece control total sobre su sistema de autenticación. Es la elección ideal para desarrolladores, fundadores de SaaS en solitario, empresas que requieren un alto grado de personalización o aquellos que desean minimizar los costos operativos a largo plazo. Usted gestiona todos los aspectos de seguridad, rendimiento y datos, lo que le brinda la máxima libertad e independencia.

Qué configuración de VPS se necesita para esta tarea

Keycloak, al ser una aplicación Java, requiere recursos suficientes, especialmente memoria RAM. La elección de la configuración óptima del VPS depende de la carga prevista: número de usuarios, frecuencia de autenticaciones y cantidad de aplicaciones conectadas.

Requisitos mínimos para una instalación pequeña (hasta 500 usuarios activos)

• CPU: 2 vCPU (núcleos virtuales). Esto será suficiente para procesar la mayoría de las solicitudes.
• RAM: 4 GB. Keycloak por sí mismo puede consumir 1.5-2 GB de RAM, más PostgreSQL y el sistema operativo.
• Disco: 50 GB SSD. El SSD es crucial para el rendimiento de la base de datos y la carga rápida de Keycloak. 50 GB serán suficientes para el SO, Keycloak y un volumen moderado de datos de la base de datos.
• Red: 100 Mbps. Para la mayoría de las tareas, esto es más que suficiente.

Plan de VPS recomendado para un proyecto mediano (hasta 5000 usuarios activos)

Para cargas más serias o si planea usar Keycloak activamente con varias aplicaciones y un gran número de usuarios, se recomienda considerar la siguiente configuración:

• CPU: 4 vCPU. Proporcionará una mejor capacidad de respuesta durante las cargas pico.
• RAM: 8 GB. Permitirá que Keycloak y PostgreSQL almacenen en caché los datos de manera más eficiente y procesen más solicitudes simultáneas.
• Disco: 100-200 GB SSD. Un mayor volumen de disco proporcionará espacio para registros, copias de seguridad y el crecimiento de la base de datos.
• Red: 1 Gbps. Para aplicaciones de alta carga.

Para alquilar un VPS con las características indicadas, puede optar por un VPS con 4 vCPU, 8 GB RAM y 100 GB SSD.

Cuándo se necesita un servidor dedicado y no un VPS

Un servidor dedicado se vuelve necesario cuando:

• Carga muy alta: Miles de solicitudes simultáneas, decenas de miles de usuarios activos.
• Requisitos de rendimiento: Se necesita un rendimiento garantizado sin "vecindad" con otros usuarios en el mismo servidor físico.
• Requisitos de hardware específicos: Por ejemplo, módulos de seguridad de hardware (HSM) o un volumen muy grande de RAM/disco.
• Normas de cumplimiento estrictas: Algunos requisitos regulatorios pueden prescribir el uso de hardware físicamente aislado.

Para estos casos, cuando se requiere el máximo rendimiento y aislamiento, se puede considerar un servidor dedicado adecuado.

Ubicación: en qué influye

La elección de la ubicación del VPS es importante por varias razones:

• Latencia: Cuanto más cerca esté el servidor de sus usuarios y aplicaciones, menor será la latencia. Esto es crítico para los servicios interactivos.
• Legislación de datos: Dependiendo de dónde se encuentren sus usuarios y dónde realice negocios, pueden aplicarse diferentes leyes sobre el almacenamiento y procesamiento de datos personales (por ejemplo, GDPR en Europa). La elección de una ubicación de servidor que cumpla con estas leyes es obligatoria.
• Disponibilidad: La ubicación de servidores en diferentes puntos geográficos puede aumentar la tolerancia a fallos de su infraestructura.

Siempre elija una ubicación que esté lo más cerca posible de la audiencia principal de sus aplicaciones.

Preparación del servidor

Antes de instalar Keycloak, es necesario realizar una configuración básica del nuevo VPS para garantizar la seguridad y estabilidad. Utilizaremos Ubuntu Server 24.04 LTS como sistema operativo.

1. Actualización del sistema

Primero, actualice todos los paquetes a sus versiones más recientes.

sudo apt update && sudo apt upgrade -y

Este comando actualiza la lista de paquetes disponibles y luego actualiza los paquetes instalados a las últimas versiones.

2. Creación de un nuevo usuario y configuración de acceso SSH

Para aumentar la seguridad, no se recomienda trabajar con la cuenta de root. Crearemos un nuevo usuario y le otorgaremos permisos sudo.

# Creamos un nuevo usuario (reemplace 'youruser' con el nombre deseado)
sudo adduser youruser
# Añadimos el usuario al grupo sudo
sudo usermod -aG sudo youruser

Ahora, copie su clave pública SSH para el nuevo usuario. Desde su máquina local:

ssh-copy-id youruser@your_vps_ip

Después de esto, salga de la sesión de root e inicie sesión con el nuevo usuario.

exit
ssh youruser@your_vps_ip

3. Configuración del servidor SSH

Deshabilite el inicio de sesión con contraseña y el inicio de sesión para el usuario root, dejando solo la autenticación por clave.

sudo nano /etc/ssh/sshd_config

Encuentre y modifique las siguientes líneas:

# Prohibir el inicio de sesión para el usuario root
PermitRootLogin no
# Prohibir el inicio de sesión con contraseña
PasswordAuthentication no
# Permitir solo la autenticación por clave
PubkeyAuthentication yes

Guarde los cambios (Ctrl+O, Enter) y salga (Ctrl+X). Reinicie el servidor SSH:

sudo systemctl restart sshd

Importante: ¡Asegúrese de poder iniciar sesión con el nuevo usuario y la clave SSH antes de cerrar la sesión actual!

4. Configuración del firewall (UFW)

Uncomplicated Firewall (UFW) es una interfaz fácil de usar para iptables. Lo configuraremos para permitir solo los puertos necesarios.

# Permitimos SSH (puerto 22, si no lo ha cambiado)
sudo ufw allow OpenSSH
# Permitimos HTTP (puerto 80)
sudo ufw allow http
# Permitimos HTTPS (puerto 443)
sudo ufw allow https
# Habilitamos el firewall
sudo ufw enable
# Verificamos el estado del firewall
sudo ufw status

La salida de sudo ufw status debería mostrar que SSH, HTTP y HTTPS están permitidos.

5. Instalación de Fail2ban

Fail2ban escanea los registros y bloquea las direcciones IP que muestran signos de actividad maliciosa (por ejemplo, múltiples intentos fallidos de inicio de sesión SSH).

# Instalamos Fail2ban
sudo apt install fail2ban -y
# Copiamos el archivo de configuración predeterminado
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local
# Iniciamos y habilitamos Fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
# Verificamos el estado
sudo systemctl status fail2ban

Fail2ban protege SSH por defecto. Puede configurarlo para proteger otros servicios editando /etc/fail2ban/jail.local.

6. Instalación de utilidades básicas

Instalaremos algunas utilidades útiles que serán de ayuda durante el proceso de configuración y monitoreo.

sudo apt install curl wget git htop net-tools -y

Ahora su servidor está listo para la instalación del software principal.

Instalación de Software — Paso a Paso

Para facilitar el despliegue y la gestión, utilizaremos Docker y Docker Compose. Esto permitirá aislar Keycloak y PostgreSQL, simplificando su actualización y configuración. Todas las versiones son actuales para el año 2026.

1. Instalación de Docker

Instalaremos Docker Engine en Ubuntu.

# Удаляем старые версии Docker, если есть
for pkg in docker.io docker-doc docker-compose docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; do sudo apt remove $pkg; done

# Устанавливаем необходимые пакеты
sudo apt install ca-certificates curl gnupg lsb-release -y

# Добавляем официальный GPG ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Добавляем репозиторий Docker в APT
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Обновляем список пакетов и устанавливаем Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# Добавляем текущего пользователя в группу docker для работы без sudo
sudo usermod -aG docker youruser

Salga de la sesión SSH actual y vuelva a iniciar sesión para que los cambios en los grupos surtan efecto. Verifique la instalación de Docker:

docker run hello-world

Si ve el mensaje de bienvenida de Docker, la instalación se realizó correctamente.

2. Instalación de Caddy (proxy inverso y TLS)

Caddy es un servidor web potente y fácil de configurar que obtiene y renueva automáticamente los certificados TLS con Let's Encrypt. Esto simplifica significativamente la configuración de HTTPS.

# Устанавливаем необходимые пакеты
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

# Добавляем официальный GPG ключ Caddy
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Добавляем репозиторий Caddy в APT
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Обновляем список пакетов и устанавливаем Caddy
sudo apt update
sudo apt install caddy -y

# Проверяем статус Caddy
sudo systemctl status caddy

Caddy se instalará como un servicio del sistema, pero no lo configuraremos todavía; esto se hará más adelante.

3. Creación del archivo Docker Compose para Keycloak y PostgreSQL

Crearemos un directorio para el proyecto Keycloak y el archivo docker-compose.yml.

mkdir keycloak-sso
cd keycloak-sso
nano docker-compose.yml

Pegue el siguiente contenido. Usaremos Keycloak 25.0.0 y PostgreSQL 17.

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:25.0.0 # Versión actual de Keycloak
    container_name: keycloak
    environment:
      KEYCLOAK_ADMIN: admin # Nombre de administrador de Keycloak
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD} # Contraseña de administrador (se tomará de .env)
      KC_DB: postgres # Usamos PostgreSQL
      KC_DB_URL: jdbc:postgresql://db:5432/keycloak # URL de la base de datos
      KC_DB_USERNAME: keycloak # Usuario de la BD
      KC_DB_PASSWORD: ${KEYCLOAK_DB_PASSWORD} # Contraseña de la BD (se tomará de .env)
      KC_HOSTNAME: ${KEYCLOAK_HOSTNAME} # Nombre de dominio de Keycloak (se tomará de .env)
      KC_PROXY: edge # Importante para el funcionamiento a través de un proxy inverso
      KC_HTTP_ENABLED: 'true' # Keycloak escuchará HTTP para el proxy
      KC_HTTP_PORT: 8080 # Puerto en el que Keycloak escucha HTTP
      KC_HEALTH_ENABLED: 'true' # Habilitamos Health Check
      KC_METRICS_ENABLED: 'true' # Habilitamos métricas
      JAVA_OPTS_APPEND: -Dquarkus.log.level=INFO -Dquarkus.log.category."org.keycloak".level=INFO # Configuración de registro
    ports:
      - "8080:8080" # Puerto interno de Keycloak, proxy por Caddy
    volumes:
      - ./keycloak-data:/opt/keycloak/data # Almacenamiento persistente de datos de Keycloak
    command: start --optimized --hostname-strict=false # Inicio de Keycloak en modo optimizado
    depends_on:
      db:
        condition: service_healthy
    restart: always

  db:
    image: postgres:17-alpine # Versión actual de PostgreSQL
    container_name: keycloak-db
    environment:
      POSTGRES_DB: keycloak # Nombre de la base de datos
      POSTGRES_USER: keycloak # Usuario de la base de datos
      POSTGRES_PASSWORD: ${KEYCLOAK_DB_PASSWORD} # Contraseña de la base de datos (se tomará de .env)
    volumes:
      - ./postgres-data:/var/lib/postgresql/data # Almacenamiento persistente de datos de la BD
    healthcheck: # Verificación de la salud de la BD
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: always

Guarde el archivo (Ctrl+O, Enter) y salga (Ctrl+X).

4. Creación del archivo .env

Para almacenar datos secretos y el nombre de dominio, crearemos el archivo .env.

nano .env

Pegue el siguiente contenido, reemplazando los marcadores de posición con sus valores reales:

KEYCLOAK_ADMIN_PASSWORD=YourStrongAdminPassword123! # Cambie a una contraseña segura
KEYCLOAK_DB_PASSWORD=YourStrongDBPassword456! # Cambie a una contraseña segura para la BD
KEYCLOAK_HOSTNAME=auth.yourdomain.com # Reemplace con su dominio para Keycloak (por ejemplo, keycloak.example.com)

Importante: Asegúrese de usar contraseñas muy seguras y de que el nombre de dominio auth.yourdomain.com (o cualquier otro que haya elegido) ya apunte a la dirección IP de su VPS en los registros DNS.

5. Inicio de Keycloak y PostgreSQL

Ahora puede iniciar los contenedores usando Docker Compose.

docker compose up -d

Este comando iniciará Keycloak y PostgreSQL en segundo plano. Docker Compose primero creará las redes y los volúmenes, luego iniciará el contenedor de PostgreSQL, esperará a que esté listo (healthcheck) y luego iniciará Keycloak.

Verifique el estado de los contenedores:

docker compose ps

Ambos contenedores deben estar en estado "running".

Configuración

Después de iniciar los contenedores de Keycloak y PostgreSQL, es necesario configurar el proxy inverso Caddy para asegurar HTTPS y el correcto funcionamiento de Keycloak con acceso externo.

1. Configuración de Caddy para Keycloak

Edite el archivo de configuración de Caddy. Por defecto, se encuentra en /etc/caddy/Caddyfile.

sudo nano /etc/caddy/Caddyfile

Elimine todo el contenido predeterminado y pegue lo siguiente. Reemplace auth.yourdomain.com con su dominio Keycloak.

auth.yourdomain.com {
    # Habilitar HTTPS automático con Let's Encrypt
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN} # Si usa Cloudflare para DNS, especifique el token API
        # Si no usa Cloudflare DNS, simplemente deje tls
    }

    # Configuración para proxy de solicitudes a Keycloak
    reverse_proxy keycloak:8080 {
        # Pasamos encabezados importantes para el correcto funcionamiento de Keycloak detrás del proxy
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
    }

    # Configuración de seguridad
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        # Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" # Configure si es necesario
    }

    # Registro
    log {
        output file /var/log/caddy/keycloak_access.log
        format json
    }
}

Nota sobre tls: Si utiliza un proveedor de DNS diferente a Cloudflare, o no desea usar el desafío DNS, puede simplemente dejar la línea tls. Caddy intentará usar el desafío HTTP-01, que requiere que el puerto 80 esté accesible desde el exterior. Si utiliza Cloudflare, como en el ejemplo, deberá crear un archivo /etc/caddy/Caddyfile.env:

sudo nano /etc/caddy/Caddyfile.env

Y añada su Token de API de Cloudflare allí:

CLOUDFLARE_API_TOKEN=YOUR_CLOUDFLARE_API_TOKEN

Asegúrese de que este token tenga permisos para gestionar los registros DNS de su dominio.

Guarde el(los) archivo(s). Verifique la configuración de Caddy y reinícielo:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Si la validación fue exitosa, Caddy se reiniciará e intentará obtener un certificado TLS.

2. Verificación de la Operatividad

Después de todas las configuraciones, es necesario asegurarse de que Keycloak esté en funcionamiento y accesible.

Verificación de contenedores

Asegúrese de que ambos contenedores estén funcionando:

docker compose ps

La salida debe mostrar State: Up para ambos servicios.

Verificación de la accesibilidad de Keycloak a través del dominio

Abra en el navegador la dirección https://auth.yourdomain.com/admin (reemplace con su dominio). Debería ver la página de inicio de sesión de la consola de administración de Keycloak.

Introduzca el nombre de usuario admin y la contraseña que especificó en el archivo .env (KEYCLOAK_ADMIN_PASSWORD).

Verificación de la configuración de OpenID Connect

Puede verificar que Keycloak esté entregando correctamente su configuración de OpenID Connect:

curl -k https://auth.yourdomain.com/realms/master/.well-known/openid-configuration

Debería recibir una respuesta JSON con los metadatos de OpenID Connect para el realm estándar master.

Si todos los pasos se han completado correctamente, Keycloak está completamente instalado y configurado para funcionar con HTTPS y la base de datos PostgreSQL.

Copias de seguridad y mantenimiento

El respaldo confiable y el mantenimiento regular son cruciales para cualquier sistema en producción. Keycloak no es una excepción, especialmente porque almacena todos los datos de usuario y las configuraciones de autenticación.

1. Qué respaldar

• Base de datos PostgreSQL: Este es el componente más importante, ya que contiene toda la información sobre usuarios, realms, clientes, roles y sesiones de Keycloak.
• Configuración de Keycloak: En nuestro caso con Docker Compose, la configuración principal de Keycloak se define en los archivos docker-compose.yml y .env. Sin embargo, si realizó algún cambio específico dentro del contenedor (lo cual no se recomienda para aplicaciones Dockerizadas), también deben ser respaldados. También es útil guardar los volúmenes keycloak-data y postgres-data.
• Configuración de Caddy: El archivo /etc/caddy/Caddyfile y, posiblemente, /etc/caddy/Caddyfile.env.
• Registros (Logs): Para depuración y auditoría. Aunque no son críticos para la recuperación, son útiles.

2. Script simple de copia de seguridad automática

Crearemos un script bash simple que realizará un volcado de la base de datos y archivará los archivos importantes.

Cree un directorio para las copias de seguridad y el script en sí:

sudo mkdir -p /var/backups/keycloak
sudo nano /usr/local/bin/keycloak_backup.sh

Pegue el siguiente contenido. Reemplace keycloak-sso con el nombre de su directorio de archivos de Docker Compose, si es diferente.

#!/bin/bash

# Ruta al directorio de archivos de Docker Compose
DOCKER_COMPOSE_DIR="/home/youruser/keycloak-sso" # Especifique la ruta completa a su directorio keycloak-sso
# Directorio para almacenar las copias de seguridad
BACKUP_DIR="/var/backups/keycloak"
# Nombre del archivo .env
ENV_FILE="${DOCKER_COMPOSE_DIR}/.env"

# Cargamos las variables de entorno desde .env
if [ -f "$ENV_FILE" ]; then
    export $(grep -v '^#' "$ENV_FILE" | xargs)
else
    echo "Error: Archivo .env no encontrado en la ruta $ENV_FILE"
    exit 1
fi

DATE=$(date +%Y%m%d%H%M%S)
BACKUP_FILENAME="${BACKUP_DIR}/keycloak_backup_${DATE}.tar.gz"
DB_DUMP_FILE="${BACKUP_DIR}/keycloak_db_dump_${DATE}.sql"

echo "Iniciando copia de seguridad de Keycloak..."

# 1. Copia de seguridad de la base de datos PostgreSQL
echo "Creando volcado de la base de datos PostgreSQL..."
docker compose -f "${DOCKER_COMPOSE_DIR}/docker-compose.yml" exec -T db pg_dump -U keycloak -d keycloak > "$DB_DUMP_FILE"
if [ $? -eq 0 ]; then
    echo "Volcado de la BD creado exitosamente: $DB_DUMP_FILE"
else
    echo "Error al crear el volcado de la BD."
    exit 1
fi

# 2. Archivando archivos y datos importantes
echo "Archivando archivos de configuración y datos..."
tar -czf "$BACKUP_FILENAME" \
    --absolute-names \
    "${DOCKER_COMPOSE_DIR}/docker-compose.yml" \
    "${DOCKER_COMPOSE_DIR}/.env" \
    "$DB_DUMP_FILE" \
    "/etc/caddy/Caddyfile" \
    "/etc/caddy/Caddyfile.env" \
    "${DOCKER_COMPOSE_DIR}/keycloak-data" \
    "${DOCKER_COMPOSE_DIR}/postgres-data" # Agregamos volúmenes persistentes

if [ $? -eq 0 ]; then
    echo "Archivo de copia de seguridad creado exitosamente: $BACKUP_FILENAME"
else
    echo "Error al crear el archivo de copia de seguridad."
    exit 1
fi

# 3. Eliminando volcado temporal de la BD
rm "$DB_DUMP_FILE"

# 4. Eliminando copias de seguridad antiguas (conservamos las últimas 7 días)
echo "Eliminando copias de seguridad antiguas (más de 7 días)..."
find "$BACKUP_DIR" -type f -name "keycloak_backup_*.tar.gz" -mtime +7 -delete

echo "Copia de seguridad de Keycloak completada."

Haga el script ejecutable:

sudo chmod +x /usr/local/bin/keycloak_backup.sh

3. Programación de copias de seguridad con Cron

Agregaremos el script a la programación de Cron para su ejecución diaria (por ejemplo, a las 3:00 AM).

sudo crontab -e

Agregue la siguiente línea al final del archivo:

0 3 * * * /usr/local/bin/keycloak_backup.sh >> /var/log/keycloak_backup.log 2>&1

Esta línea ejecutará el script todos los días a las 3:00 de la madrugada, y la salida se redirigirá al archivo de registro /var/log/keycloak_backup.log.

4. Dónde almacenar las copias de seguridad (almacenamiento externo)

Almacenar las copias de seguridad en el mismo servidor que el servicio principal es arriesgado. En caso de fallo del servidor, perderá tanto los datos como las copias de seguridad. Se recomienda utilizar un almacenamiento externo:

• Almacenamiento de objetos en la nube (compatible con S3): Amazon S3, DigitalOcean Spaces, Backblaze B2. Es una solución económica y confiable. Puede usar utilidades como s3cmd o rclone para la carga automática de copias de seguridad.
• VPS separado: Si tiene otro VPS, puede configurar rsync o scp para copiar las copias de seguridad a él.
• Soluciones especializadas: BorgBackup o Restic para copias de seguridad deduplicadas y cifradas.

Por ejemplo, para subir a S3 usando rclone, agregaría una línea al script después de crear el archivo:

# rclone copy "$BACKUP_FILENAME" "remote_s3_storage:keycloak-backups/"

Habiendo configurado previamente rclone con sus credenciales S3.

5. Actualizaciones: rolling vs. ventana de mantenimiento

• Actualización de SO y Docker: Actualice regularmente el sistema operativo y Docker. Para Ubuntu, esto es sudo apt update && sudo apt upgrade -y. Hágalo en un horario planificado, ya que a veces se requiere un reinicio del servidor.
• Actualización de Keycloak: Para Keycloak en Docker Compose, esto se reduce a cambiar la versión de la imagen en docker-compose.yml (por ejemplo, de 25.0.0 a 25.0.1) y luego ejecutar docker compose pull keycloak && docker compose up -d. Antes de actualizar, lea siempre las notas de la versión, ya que puede haber cambios en la configuración o migraciones de la BD.
• Actualización de PostgreSQL: La actualización de versiones mayores de PostgreSQL (por ejemplo, de 16 a 17) requiere un procedimiento de migración de datos más complejo. Esto siempre debe realizarse dentro de una "ventana de mantenimiento" planificada con una copia de seguridad previa. Las actualizaciones menores (por ejemplo, 17.0 a 17.1) suelen ser seguras y no requieren migración.

Para sistemas en producción, siempre se recomienda tener un entorno de prueba donde pueda verificar las actualizaciones antes de aplicarlas en el servidor principal.

Solución de problemas + Preguntas frecuentes

En esta sección, abordaremos los problemas típicos que pueden surgir durante la instalación y configuración de Keycloak, y responderemos a las preguntas frecuentes.

Keycloak no se inicia / Error de conexión a la BD

Problema: El contenedor de Keycloak se reinicia constantemente o muestra errores de conexión a la base de datos en los registros. Qué verificar:

1. Registros de Keycloak: docker compose logs keycloak. Busque mensajes de error de conexión a PostgreSQL.
2. Registros de PostgreSQL: docker compose logs db. Asegúrese de que PostgreSQL se haya iniciado correctamente y esté escuchando conexiones.
3. Variables de entorno: Verifique la exactitud de KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD en docker-compose.yml y .env. Asegúrese de que las contraseñas coincidan.
4. Healthcheck de PostgreSQL: Asegúrese de que el healthcheck para el contenedor db se complete con éxito (docker compose ps). Keycloak no se iniciará hasta que la BD esté lista.

No puedo acceder a la administración de Keycloak a través del dominio

Problema: Al intentar abrir https://auth.yourdomain.com/admin, el navegador muestra un error "Connection refused" o "ERR_CONNECTION_CLOSED". Qué verificar:

1. Registro DNS: Asegúrese de que su dominio (por ejemplo, auth.yourdomain.com) apunte correctamente a la dirección IP de su VPS. Use dig auth.yourdomain.com.
2. Cortafuegos (UFW): Verifique que los puertos 80 y 443 estén abiertos: sudo ufw status.
3. Caddy: Verifique el estado de Caddy: sudo systemctl status caddy. Asegúrese de que esté en ejecución y no haya errores en sus registros: sudo journalctl -u caddy.
4. Configuración de Caddyfile: Verifique que el dominio en Caddyfile coincida con el suyo y que reverse_proxy apunte correctamente al contenedor de Keycloak (keycloak:8080).
5. Variable KC_PROXY: Asegúrese de que la variable KC_PROXY: edge esté configurada para Keycloak en docker-compose.yml.

Problemas con HTTPS / Caddy no obtiene el certificado

Problema: Caddy no puede obtener un certificado TLS de Let's Encrypt, y el sitio solo está disponible por HTTP (o no está disponible en absoluto). Qué verificar:

1. Registros de Caddy: sudo journalctl -u caddy --no-pager. Busque errores relacionados con tls o Let's Encrypt.
2. Disponibilidad del puerto 80/443: Asegúrese de que ningún otro servicio esté utilizando los puertos 80 o 443. (sudo lsof -i :80, sudo lsof -i :443).
3. Registro DNS: Asegúrese de que su dominio apunte correctamente a su VPS. Let's Encrypt verifica la propiedad del dominio.
4. Configuración del desafío DNS (si se usa): Si está utilizando tls { dns ... }, verifique que la variable de entorno con el token API esté configurada correctamente y que el token tenga los permisos necesarios.

¿Cómo restablecer la contraseña de administrador de Keycloak?

Problema: Ha olvidado la contraseña de administrador de Keycloak. Qué verificar: La contraseña de administrador se establece mediante la variable KEYCLOAK_ADMIN_PASSWORD en el archivo .env. Cómo solucionar:

1. Edite el archivo .env y cambie el valor de KEYCLOAK_ADMIN_PASSWORD a una nueva contraseña segura.
2. Reinicie el contenedor de Keycloak para que los cambios surtan efecto: docker compose restart keycloak.
3. Ahora podrá iniciar sesión en la consola de administración con la nueva contraseña.

¿Qué configuración mínima de VPS es adecuada?

La configuración mínima de VPS adecuada para instalar Keycloak para un proyecto pequeño (hasta 500 usuarios activos) incluye 2 vCPU, 4 GB de RAM y 50 GB de disco SSD. Esto debería ser suficiente para ejecutar el sistema operativo, Keycloak y su base de datos PostgreSQL. Es importante que el disco sea SSD para garantizar un rendimiento adecuado de la base de datos. Con el aumento de la carga o el número de usuarios, será necesario escalar los recursos.

¿Qué elegir: VPS o dedicado para esta tarea?

La elección entre un VPS y un servidor dedicado depende de la escala de su proyecto y de los requisitos de rendimiento. Para la mayoría de las startups, equipos pequeños y medianos, así como proyectos individuales, un VPS será la opción óptima. Es económico, flexible y fácilmente escalable. Un servidor dedicado se vuelve preferible para sistemas de alta carga con miles de usuarios concurrentes, rendimiento críticamente importante, requisitos estrictos de aislamiento de recursos o necesidades de hardware específicas que no pueden satisfacerse en una máquina virtual.

¿Cómo escalar Keycloak?

Problema: Su instalación de Keycloak experimenta una alta carga y el rendimiento del VPS actual es insuficiente. Qué verificar: Monitoreo de CPU, RAM, I/O de disco en su VPS. Registros de Keycloak en busca de retrasos o errores. Cómo solucionar:

1. Escalado vertical (Scale Up): Aumente los recursos de su VPS actual (CPU, RAM, Disco). Este es el primer paso más sencillo.
2. Escalado horizontal (Scale Out): Implemente varias instancias de Keycloak detrás de un balanceador de carga. Esto requiere configurar Keycloak en modo clúster (con una base de datos y caché compartidas).
3. Optimización de la base de datos: Asegúrese de que PostgreSQL tenga suficientes recursos y esté configurado para un rendimiento óptimo.
4. Optimización de Keycloak: Configure los parámetros de JVM, almacenamiento en caché y registro para un mejor rendimiento.

Conclusiones y próximos pasos

¡Felicidades! Ha instalado y configurado Keycloak con éxito en su VPS, creando una plataforma robusta para la gestión de identidad y acceso con inicio de sesión único. Ahora tiene una solución de autenticación centralizada que mejora la seguridad y simplifica la gestión de usuarios para sus aplicaciones.

Los siguientes pasos para el desarrollo posterior de su sistema son:

• Integración de aplicaciones: Conecte sus aplicaciones web, API o microservicios a Keycloak, utilizando los adaptadores disponibles o los protocolos estándar OpenID Connect/OAuth 2.0.
• Configuración avanzada: Explore las características adicionales de Keycloak, como la personalización de temas, la adición de autenticación multifactor (MFA), la federación con proveedores de identidad externos (LDAP, Active Directory, redes sociales).
• Monitoreo y tolerancia a fallos: Configure un sistema de monitoreo (por ejemplo, Prometheus + Grafana) para rastrear el rendimiento de Keycloak. Para entornos de producción de alta carga, considere la posibilidad de la agrupación en clústeres de Keycloak para garantizar una alta disponibilidad.