Keycloak en un VPS: instalación, configuración y mantenimiento

Keycloak en un VPS es una forma eficaz de implementar un potente sistema de gestión de identidad y acceso (IAM) para sus aplicaciones, proporcionando autenticación y autorización centralizadas con control total sobre los datos y la infraestructura.

¿Qué es Keycloak y por qué debería implementarlo en un VPS?

Keycloak es una solución de código abierto para la gestión de identidad y acceso (Identity and Access Management, IAM), desarrollada por Red Hat. Proporciona una amplia gama de funciones para la autenticación y autorización seguras de usuarios en aplicaciones web, aplicaciones móviles y servicios RESTful. Con él, puede agregar fácilmente Single Sign-On (SSO), autenticación federada, soporte para los estándares OpenID Connect, OAuth 2.0 y SAML 2.0, así como gestión de usuarios y roles.

La implementación de Keycloak en un VPS es una solución óptima para muchas empresas y desarrolladores que necesitan control total sobre su solución IAM sin costosas suscripciones en la nube o las limitaciones de los servicios SaaS. Esto permite obtener flexibilidad de configuración, escalabilidad y seguridad, adaptadas a las necesidades específicas de su proyecto o negocio. Usted se convierte en el propietario total de los datos y no depende de proveedores externos, lo cual es fundamental para el cumplimiento normativo y la privacidad.

Capacidades de Keycloak: de SSO a MFA

Keycloak no solo proporciona autenticación básica; es una plataforma integral con una multitud de funciones avanzadas:

• Single Sign-On (SSO): Los usuarios solo necesitan iniciar sesión una vez para acceder a todas las aplicaciones conectadas. Esto mejora significativamente la experiencia del usuario y reduce la carga de soporte.
• Soporte de estándares: La compatibilidad total con OpenID Connect, OAuth 2.0 y SAML 2.0 convierte a Keycloak en una solución universal que se integra fácilmente con la mayoría de las aplicaciones y servicios modernos.
• Autenticación multifactor (MFA): El soporte integrado para varios métodos de MFA, como OTP (contraseñas de un solo uso) a través de Google Authenticator o FreeOTP, aumenta el nivel de seguridad.
• Gestión de usuarios y roles: Una interfaz de administración fácil de usar permite crear y gestionar usuarios, grupos, roles y permisos.
• Autenticación a través de redes sociales: La capacidad de integrarse con proveedores populares como Google, Facebook, GitHub, simplifica el proceso de registro e inicio de sesión para los usuarios.
• Autenticación federada: Soporte para LDAP y Active Directory para sincronizar usuarios con directorios corporativos existentes.
• Adaptadores de cliente: Adaptadores listos para usar para frameworks y lenguajes de programación populares (Java, JavaScript, Node.js, Python, etc.) aceleran la integración de Keycloak en sus aplicaciones.
• Tematización: La capacidad de personalizar completamente la apariencia de las páginas de inicio de sesión, registro y gestión de cuentas para que coincidan con la identidad de su marca.

Ventajas de Keycloak self-hosted en un VPS

La elección de un VPS para implementar Keycloak en formato Keycloak self-hosted ofrece una serie de ventajas clave que no están disponibles al utilizar servicios en la nube o hosting compartido:

• Control total: Usted controla completamente toda la infraestructura, desde el sistema operativo hasta la configuración de Keycloak y la base de datos. Esto es fundamental para el cumplimiento normativo y las configuraciones de seguridad específicas.
• Flexibilidad y personalización: Un VPS permite instalar cualquier servicio adicional, modificar configuraciones y adaptar Keycloak a los requisitos únicos de su proyecto. Puede elegir versiones de software, parches y extensiones sin restricciones.
• Ahorro de costos: Para proyectos medianos y grandes, Keycloak en un servidor en un VPS a menudo resulta significativamente más económico que las soluciones IAM en la nube de pago, especialmente con el uso a largo plazo. Solo paga por los recursos que realmente utiliza.
• Rendimiento: Los recursos dedicados de un VPS garantizan un rendimiento predecible, lo cual es crucial para un sistema de autenticación que debe estar siempre disponible y responder rápidamente. Puede elegir discos NVMe de alto rendimiento y potentes procesadores.
• Seguridad: Usted mismo gestiona la seguridad de su infraestructura, incluyendo la configuración de red, firewalls y actualizaciones. Esto permite implementar políticas de seguridad que pueden no estar disponibles con proveedores externos.
• Escalabilidad: A medida que su proyecto crece, puede escalar fácilmente los recursos del VPS (CPU, RAM, disco) o incluso migrar a un servidor dedicado, manteniendo la misma arquitectura de Keycloak.

Este enfoque no solo proporciona independencia, sino también la posibilidad de una optimización profunda para tareas específicas, ya sea una pequeña aplicación corporativa o un gran servicio multiusuario.

Requisitos del sistema de Keycloak: ¿qué VPS elegir?

La elección de un Keycloak VPS adecuado es fundamental para garantizar un funcionamiento estable y rápido de su sistema de autenticación. Los requisitos de recursos dependen de la carga esperada: el número de usuarios activos, la frecuencia de las autenticaciones, la complejidad de las integraciones y el volumen de datos almacenados.

Requisitos mínimos para un entorno de prueba

Para fines de desarrollo, pruebas o para proyectos muy pequeños con una carga mínima (hasta 10-20 usuarios simultáneos, varios cientos de autenticaciones al día), se pueden utilizar recursos modestos:

• Procesador (CPU): 1-2 vCPU. Keycloak puede utilizar varios núcleos, pero para una carga mínima, un solo núcleo con una buena frecuencia (2.0+ GHz) será suficiente.
• Memoria RAM: 2 GB. Keycloak en Java requiere suficiente memoria. 2 GB es el mínimo absoluto para un funcionamiento estable con el sistema operativo y la base de datos. Se recomienda asignar alrededor de 1-1.5 GB para la JVM.
• Espacio en disco: 20-30 GB NVMe/SSD. NVMe acelerará significativamente el inicio y el trabajo con la base de datos, pero para pruebas, un SSD normal será suficiente. El volumen principal es necesario para el sistema operativo, las imágenes de Docker, Keycloak en sí y la base de datos.
• Sistema operativo: Ubuntu Server 22.04+, Debian 11+, CentOS Stream 9+. Se prefieren las distribuciones ligeras.
• Base de datos: H2 integrada (¡solo para pruebas!) o PostgreSQL/MySQL externo. Para producción, H2 es categóricamente inadecuado.

Por ejemplo, un VPS de Valebyte con 2 vCPU, 2 GB de RAM y 40 GB de disco NVMe (con un costo de alrededor de $5-10/mes) será suficiente para empezar.

Recomendaciones para un entorno de producción

Para un entorno de producción, donde la fiabilidad, el rendimiento y la escalabilidad son importantes, los requisitos de recursos aumentan significativamente. Aquí hablaremos de Keycloak en un servidor que es capaz de soportar una carga real.

• Procesador (CPU): 2-4 vCPU (o más) con una frecuencia de 2.5+ GHz. Keycloak utiliza activamente la CPU para el cifrado, el hash de contraseñas y el procesamiento de solicitudes. Para 100-200 usuarios simultáneos y 50-100 solicitudes por segundo (RPS), 2-4 vCPU serán un buen comienzo.
• Memoria RAM: 4-8 GB. Para un funcionamiento estable de Keycloak y PostgreSQL (BD recomendada) se necesitarán al menos 4 GB, y preferiblemente 8 GB. Esto permitirá que la JVM funcione cómodamente, almacene datos en caché y evite el swapping.
• Espacio en disco: 50-100 GB NVMe. Los discos NVMe son cruciales para el rendimiento de la base de datos de Keycloak. Un mayor volumen proporcionará espacio para logs, copias de seguridad y el crecimiento de la base de datos.
• Sistema operativo: Ubuntu Server 22.04+ LTS. Estable, bien mantenido y con amplia documentación.
• Base de datos: PostgreSQL 13+ (recomendado) o MySQL 8+. Implemente la base de datos en un contenedor separado en el mismo VPS, o en una instancia de base de datos separada para alta disponibilidad y rendimiento.

Al elegir un VPS, siempre considere la posibilidad de una rápida actualización de recursos. Valebyte ofrece planes flexibles que le permiten escalar fácilmente la CPU, la RAM y el espacio en disco a medida que crecen las necesidades de su Keycloak en el servidor.

Preparación del VPS para la instalación de Keycloak: pasos básicos

Antes de proceder con la instalación de Keycloak, es necesario preparar cuidadosamente su VPS. Esto incluye la selección del sistema operativo, la actualización de paquetes, la configuración del firewall y la instalación de Docker, la herramienta principal para la implementación de Keycloak.

Elección del sistema operativo y configuración inicial

Para Keycloak, se recomienda utilizar distribuciones de Linux estables y bien mantenidas. Las más populares y convenientes para la administración son:

• Ubuntu Server LTS: Se recomienda 22.04 LTS (Jammy Jellyfish) o más reciente. Se caracteriza por una buena documentación, una gran comunidad y frecuentes actualizaciones de seguridad.
• Debian Stable: Versiones 11 (Bullseye) o 12 (Bookworm). Conocido por su estabilidad y minimalismo.

Después de implementar el VPS, siga estos pasos básicos:

1. Conexión por SSH:

   ssh root@su_direccion_ip_vps

2. Actualización del sistema: Siempre comience actualizando todos los paquetes instalados a las últimas versiones. Esto garantiza que tendrá los parches de seguridad y correcciones de errores más recientes.

   sudo apt update && sudo apt upgrade -y

   (Para Debian/Ubuntu)

   sudo dnf update -y

   (Para CentOS Stream/Rocky Linux)
3. Configuración del firewall (UFW para Ubuntu): Habilite el firewall y permita solo los puertos necesarios (SSH, HTTP, HTTPS).

   sudo ufw enable
   sudo ufw allow ssh
   sudo ufw allow http
   sudo ufw allow https
   sudo ufw status

4. Creación de un usuario normal (opcional, pero recomendado): Trabajar como root no siempre es seguro. Cree un nuevo usuario y otórguele permisos de sudo.

   adduser su_usuario
   usermod -aG sudo su_usuario
   su - su_usuario

Instalación de Docker y Docker Compose

Keycloak se implementará en contenedores Docker, lo que simplifica la gestión, el aislamiento y la escalabilidad. Los contenedores permiten migrar fácilmente la aplicación entre entornos y garantizan la coherencia. Docker Compose nos ayudará a definir y ejecutar una aplicación multicontenedor.

1. Instalación de Docker Engine: El script oficial de instalación de Docker es la forma más sencilla.

   sudo apt install ca-certificates curl gnupg -y
   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
   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
   sudo apt update
   sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

   Verifique la instalación de Docker:

   sudo docker run hello-world

   Si no está trabajando como root, agregue el usuario al grupo docker:

   sudo usermod -aG docker su_usuario
   newgrp docker

   (Cierre sesión y vuelva a iniciarla o use newgrp docker para aplicar los cambios.)
2. Instalación de Docker Compose: Docker Compose ahora se instala como un plugin de Docker, por lo que el comando docker-compose-plugin del paso anterior ya lo habrá instalado. Verifique la versión de Docker Compose:

   docker compose version

   Debería ver algo como Docker Compose version v2.x.x.

Su VPS está listo para la implementación de Keycloak. Ahora podemos pasar a crear la configuración de Docker Compose y lanzar Keycloak.

Instalación paso a paso de Keycloak en un VPS con Docker Compose

La implementación de Keycloak utilizando Keycloak Docker y Docker Compose es la forma de instalación más recomendada y flexible. Permite gestionar fácilmente las dependencias (por ejemplo, la base de datos), configurar el entorno y actualizar los componentes.

Creación del archivo docker-compose.yml para Keycloak

Crearemos un archivo docker-compose.yml que describirá dos servicios: Keycloak y la base de datos PostgreSQL. Se recomienda utilizar PostgreSQL como una base de datos estable y de alto rendimiento para entornos de producción.

Cree un directorio para su proyecto Keycloak y navegue hasta él:

mkdir ~/keycloak
cd ~/keycloak

Cree el archivo docker-compose.yml:

nano docker-compose.yml

E inserte el siguiente contenido. Asegúrese de reemplazar YOUR_KEYCLOAK_ADMIN_PASSWORD y YOUR_POSTGRES_PASSWORD con contraseñas seguras.

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    container_name: keycloak
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: YOUR_KEYCLOAK_ADMIN_PASSWORD
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://db:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: YOUR_POSTGRES_PASSWORD
      KC_HOSTNAME: auth.yourdomain.com # Reemplace con su dominio
      KC_HTTP_PORT: 8080
      KC_HTTPS_PORT: 8443
      KC_PROXY: edge # Importante para trabajar con reverse proxy
      KC_HEALTH_ENABLED: true
      KC_METRICS_ENABLED: true
      # Los siguientes parámetros son para optimización de producción:
      KC_FEATURES: token-exchange,admin-fine-grained-authz
      KC_LOG_LEVEL: INFO
      KC_OPTIMIZED: 'true' # Habilita la optimización para producción
    ports:
      - "8080:8080" # Puerto interno de Keycloak, será proxy por Nginx/Caddy
      - "8443:8443" # Puerto HTTPS de Keycloak (para acceso directo, si no hay proxy)
    volumes:
      - ./keycloak_data:/opt/keycloak/data # Para almacenar datos de Keycloak (caché, logs, etc.)
    depends_on:
      - db
    restart: always

  db:
    image: postgres:15-alpine
    container_name: keycloak_db
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: YOUR_POSTGRES_PASSWORD
    volumes:
      - ./postgres_data:/var/lib/postgresql/data # Para almacenamiento persistente de datos de la BD
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  keycloak_data:
  postgres_data:

Explicaciones del archivo docker-compose.yml:

• image: quay.io/keycloak/keycloak:latest: Utiliza la imagen oficial de Keycloak. Se recomienda usar una versión específica en lugar de latest para producción.
• KEYCLOAK_ADMIN y KEYCLOAK_ADMIN_PASSWORD: Credenciales para el primer inicio de sesión en la consola de administración. ¡Asegúrese de cambiar la contraseña!
• KC_DB, KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD: Configuración de conexión a la base de datos PostgreSQL.
• KC_HOSTNAME: Parámetro muy importante. Especifique el nombre de dominio a través del cual Keycloak será accesible (por ejemplo, auth.yourdomain.com). Esto es necesario para la correcta generación de URL en Keycloak.
• KC_PROXY: edge: Este parámetro le indica a Keycloak que está funcionando detrás de un proxy inverso (Nginx/Caddy) que manejará el SSL.
• KC_OPTIMIZED: 'true': Habilita optimizaciones para el entorno de producción, como la compilación previa de plantillas y el almacenamiento en caché.
• ports: Abrimos los puertos 8080 y 8443. En producción, el acceso a ellos será a través de un reverse proxy, por lo que se podrán restringir con un firewall solo para localhost.
• volumes: Utilizamos volúmenes con nombre (keycloak_data, postgres_data) para el almacenamiento persistente de datos. Esto significa que al reiniciar o actualizar los contenedores, sus datos no se perderán.
• depends_on: - db: Indica que el servicio keycloak depende del servicio db y se iniciará después de este.
• healthcheck para db: Garantiza que Keycloak no intentará conectarse a la base de datos hasta que esta se haya iniciado completamente y esté lista para aceptar conexiones.

Inicio y configuración inicial de Keycloak

Después de crear el archivo docker-compose.yml, puede iniciar Keycloak:

docker compose up -d

La opción -d inicia los contenedores en segundo plano. El proceso de inicio puede tardar varios minutos, especialmente la primera vez, ya que Docker descargará las imágenes y Keycloak realizará la configuración inicial de la base de datos.

Puede verificar el estado de los contenedores:

docker compose ps

Y ver los logs de Keycloak para asegurarse de que se ha iniciado correctamente:

docker compose logs -f keycloak

Espere el mensaje de que Keycloak se ha iniciado correctamente. Después de eso, Keycloak estará disponible en http://su_direccion_ip_vps:8080. Podrá iniciar sesión en la consola de administración en http://su_direccion_ip_vps:8080/admin, utilizando las credenciales admin y YOUR_KEYCLOAK_ADMIN_PASSWORD que especificó en docker-compose.yml.

Importante: El acceso directo por IP:puerto sin HTTPS es altamente desaconsejable para un entorno de producción. En el siguiente paso, configuraremos un reverse proxy y HTTPS.

Configuración de Reverse Proxy (Nginx/Caddy) y HTTPS para Keycloak

Para garantizar la seguridad y disponibilidad de Keycloak en un entorno de producción, es necesario utilizar un reverse proxy y HTTPS. Un reverse proxy (por ejemplo, Nginx o Caddy) aceptará todas las solicitudes entrantes en los puertos estándar (80 para HTTP y 443 para HTTPS), las reenviará al contenedor de Keycloak y gestionará los certificados SSL. Esto permite ocultar el puerto interno de Keycloak y garantizar el cifrado del tráfico.

Configuración de Nginx como Reverse Proxy

Nginx es un servidor web potente y ampliamente utilizado que es excelente para funcionar como proxy inverso. Instale Nginx si aún no está instalado:

sudo apt install nginx -y

Cree un nuevo archivo de configuración para su dominio (por ejemplo, auth.yourdomain.com) en el directorio /etc/nginx/sites-available/:

sudo nano /etc/nginx/sites-available/keycloak.conf

Inserte el siguiente contenido, reemplazando auth.yourdomain.com con su dominio real:

server {
    listen 80;
    server_name auth.yourdomain.com; # Reemplace con su dominio

    location / {
        proxy_pass http://127.0.0.1:8080; # Keycloak funciona en el puerto 8080
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_redirect off;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_max_temp_file_size 0;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        proxy_connect_timeout 300s;

        # Para WebSocket (si Keycloak los usa, por ejemplo, para la consola de administración)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Cree un enlace simbólico a este archivo desde sites-enabled para que Nginx comience a usarlo:

sudo ln -s /etc/nginx/sites-available/keycloak.conf /etc/nginx/sites-enabled/

Elimine la configuración predeterminada de Nginx para evitar conflictos:

sudo rm /etc/nginx/sites-enabled/default

Verifique la sintaxis de la configuración de Nginx y recárguelo:

sudo nginx -t
sudo systemctl reload nginx

Ahora su Keycloak debería estar accesible por HTTP en http://auth.yourdomain.com.

Obtención y renovación automática de certificados SSL con Let's Encrypt

Para activar HTTPS, utilizaremos Certbot y Let's Encrypt, que proporcionan certificados SSL gratuitos y automatizados. Instale Certbot y el plugin de Nginx para él:

sudo apt install certbot python3-certbot-nginx -y

Ejecute Certbot para obtener un certificado y configurar Nginx automáticamente:

sudo certbot --nginx -d auth.yourdomain.com

Certbot le hará algunas preguntas: ingrese su correo electrónico, acepte los términos y elija si desea forzar la redirección de HTTP a HTTPS (recomendado).

Después de una ejecución exitosa, Certbot actualizará automáticamente su configuración de Nginx, agregando la configuración HTTPS. Verifique la renovación automática de Certbot:

sudo systemctl status certbot.timer

Esto mostrará que Certbot está configurado para renovar automáticamente los certificados antes de su vencimiento. Ahora su Keycloak estará disponible en https://auth.yourdomain.com, y todo el tráfico estará cifrado.

Alternativa: Caddy para simplificar

Si busca una solución más sencilla para un proxy inverso con HTTPS automático, Caddy es una excelente opción. Obtiene y renueva automáticamente los certificados SSL para los dominios especificados. Instale Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

Cree el archivo Caddyfile:

sudo nano /etc/caddy/Caddyfile

E inserte el siguiente contenido, reemplazando auth.yourdomain.com con su dominio:

auth.yourdomain.com {
    reverse_proxy 127.0.0.1:8080 {
        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}
        header_up X-Forwarded-Port {server_port}
        transport http {
            keepalive_interval 30s
            read_timeout 300s
            write_timeout 300s
        }
    }
}

Verifique la configuración de Caddy y reinícielo:

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

Caddy obtendrá automáticamente un certificado SSL y configurará HTTPS para su dominio. Esto simplifica significativamente la configuración en comparación con Nginx+Certbot, pero Nginx puede ofrecer más flexibilidad para configuraciones avanzadas.

Mantenimiento de Keycloak: copias de seguridad, actualizaciones y monitoreo

Después de una instalación exitosa de Keycloak en un Keycloak VPS, es crucial garantizar su mantenimiento adecuado. Esto incluye copias de seguridad regulares de los datos, actualizaciones oportunas y un monitoreo constante del rendimiento y la disponibilidad. Estos pasos garantizan la fiabilidad y seguridad de su sistema de autenticación.

Estrategias de copia de seguridad de la base de datos de Keycloak

Los datos de Keycloak se almacenan principalmente en la base de datos (usuarios, roles, clientes, sesiones). Por lo tanto, la copia de seguridad de la base de datos es el aspecto más crítico. Utilizamos PostgreSQL, así que nos centraremos en sus herramientas.

Opción 1: Copia de seguridad desde dentro del contenedor PostgreSQL

Esta es la forma más directa. Ejecute el siguiente comando en su VPS:

docker exec keycloak_db pg_dumpall -U keycloak > ~/keycloak_backup/keycloak_db_$(date +%Y%m%d%H%M%S).sql

Explicaciones:

• docker exec keycloak_db: Ejecuta el comando dentro del contenedor de la base de datos llamado keycloak_db.
• pg_dumpall -U keycloak: Utilidad de PostgreSQL para crear un volcado completo de todas las bases de datos. -U keycloak especifica el usuario de la base de datos.
• > ~/keycloak_backup/keycloak_db_$(date +%Y%m%d%H%M%S).sql: Redirige la salida a un archivo con un nombre único que contiene una marca de tiempo.

Opción 2: Copia de seguridad usando Docker Compose (para crear un volcado desde el servicio)

Puede agregar un servicio separado para copias de seguridad en su docker-compose.yml o ejecutar el comando manualmente:

docker compose exec db pg_dumpall -U keycloak > ~/keycloak_backup/keycloak_db_$(date +%Y%m%d%H%M%S).sql

Recomendaciones para copias de seguridad:

1. Automatización: Configure una tarea cron para realizar copias de seguridad automáticamente a diario o varias veces al día, dependiendo de la frecuencia de los cambios y los requisitos de RPO (Recovery Point Objective).

   0 3 * * * docker exec keycloak_db pg_dumpall -U keycloak > /root/keycloak_backup/keycloak_db_$(date +\%Y\%m\%d\%H\%M\%S).sql

   (Este comando realizará una copia de seguridad a las 03:00 todos los días.)
2. Almacenamiento: Almacene las copias de seguridad no solo en el mismo VPS, sino también en un almacenamiento externo (S3, Dropbox, otro servidor) para protegerse contra una falla total del VPS.
3. Rotación: Implemente una política de rotación de copias de seguridad para evitar llenar el disco (por ejemplo, mantener las copias de seguridad de los últimos 7 días).
4. Verificación: Verifique periódicamente la funcionalidad de las copias de seguridad restaurándolas en un servidor de prueba.

Proceso de actualización del contenedor de Keycloak

La actualización de Keycloak, implementado a través de Docker Compose, es relativamente sencilla, pero requiere precaución y pruebas previas.

1. Cree una copia de seguridad: Antes de cualquier actualización, obligatoriamente realice una copia de seguridad completa de la base de datos de Keycloak.
2. Detenga los contenedores actuales:

   cd ~/keycloak # Vaya al directorio con docker-compose.yml
   docker compose down

3. Actualice la imagen de Keycloak: Cambie la etiqueta de la imagen en docker-compose.yml de :latest a una versión nueva y específica (por ejemplo, :22.0.5). Luego, descargue la nueva imagen:

   docker compose pull keycloak

4. Inicie los contenedores actualizados:

   docker compose up -d

   Keycloak aplicará automáticamente las migraciones necesarias a la base de datos en el primer inicio de la nueva versión.
5. Verifique los logs: Asegúrese de que Keycloak se haya iniciado sin errores:

   docker compose logs -f keycloak

6. Verifique la funcionalidad: Inicie sesión en la consola de administración y pruebe las funciones principales de autenticación y autorización.

Importante: Siempre lea la documentación oficial de actualización de Keycloak antes de realizar una actualización, ya que puede haber cambios entre versiones principales que requieran acciones adicionales.

Monitoreo de rendimiento y disponibilidad

El monitoreo de Keycloak en el servidor es esencial para la detección temprana de problemas, la prevención de tiempos de inactividad y la optimización de recursos.

Métricas clave para el monitoreo:

• Disponibilidad del servicio: Verificar si Keycloak responde a las solicitudes (por ejemplo, mediante un ping o una solicitud HTTP al endpoint /auth/realms/master/.well-known/openid-configuration).
• Uso de CPU: Una alta carga de CPU puede indicar falta de recursos o solicitudes ineficientes.
• Uso de RAM: Monitoree el consumo de memoria de Keycloak y la base de datos. Si se acerca al límite, puede provocar ralentizaciones o fallos.
• Operaciones de E/S de disco (IOPS): Valores altos de IOPS, especialmente en el disco de la base de datos, pueden indicar un "cuello de botella" en el subsistema de disco.
• Métricas de la base de datos: Tiempo de ejecución de consultas, número de conexiones activas, tamaño de la base de datos.
• Logs de Keycloak: Revise regularmente los logs en busca de errores, advertencias o actividad sospechosa.

Herramientas de monitoreo:

• Netdata: Una excelente herramienta para monitorear los recursos del VPS en tiempo real. Es fácil de instalar y proporciona gráficos detallados de CPU, RAM, disco, red y contenedores Docker. Puede obtener más información sobre la instalación de Netdata en un VPS en nuestro artículo.
• Prometheus y Grafana: Una solución más avanzada para la recopilación, almacenamiento y visualización de métricas. Keycloak proporciona endpoints para Prometheus (/health y /metrics, si KC_HEALTH_ENABLED y KC_METRICS_ENABLED están habilitados).
• Agregadores de logs: Para recopilar y analizar logs de todos los contenedores, utilice soluciones como ELK Stack (Elasticsearch, Logstash, Kibana) o Loki+Grafana.

El monitoreo regular le permitirá reaccionar rápidamente a los problemas y mantener un alto nivel de fiabilidad de su sistema IAM.

Configuración óptima de VPS para Keycloak bajo carga real

La elección de la configuración correcta de Keycloak VPS es clave para garantizar un rendimiento estable y escalabilidad bajo carga real. Recursos insuficientes provocarán ralentizaciones, errores y fallos, mientras que los excesivos generarán gastos innecesarios. La elección óptima depende del número de usuarios, la cantidad esperada de solicitudes por segundo (RPS) y otros factores.

Análisis de los factores que afectan el rendimiento

Al determinar la configuración necesaria del VPS para Keycloak, considere los siguientes factores:

• Número de usuarios activos: Cuántos usuarios se autenticarán o gestionarán sus cuentas simultáneamente.
• Frecuencia de autenticaciones (RPS): El número de solicitudes de inicio de sesión por segundo. Este es uno de los procesos que más recursos consume.
• Tipo de autenticación: Los inicios de sesión simples con usuario/contraseña son menos exigentes que MFA, la autenticación federada a través de LDAP o las políticas de autorización complejas.
• Número de clientes/aplicaciones: Cuantos más clientes estén integrados con Keycloak, más recursos pueden ser necesarios para su gestión y la emisión de tokens.
• Uso de caché: Un almacenamiento en caché eficiente reduce significativamente la carga en la base de datos y la CPU.
• Volumen de datos: El número de usuarios, grupos, roles y sesiones almacenados en la base de datos. Una base de datos grande requiere más espacio en disco y puede afectar la velocidad de las consultas.
• Servicios adicionales: Si otras aplicaciones o servicios se ejecutarán en el mismo VPS, sus requisitos también deben tenerse en cuenta.

Keycloak en Java y PostgreSQL utilizan activamente la CPU y la RAM. El subsistema de disco debe ser rápido (NVMe) para la base de datos.

Para una selección más detallada del VPS, preste atención a los tipos de virtualización, como KVM, que proporcionan recursos más aislados y de mayor rendimiento en comparación con OpenVZ. Puede obtener más información al respecto en el artículo KVM VPS vs OpenVZ VPS en 2026.

Tabla: Recomendaciones de configuración de VPS para Keycloak

A continuación se presenta una tabla con recomendaciones para la configuración de Keycloak VPS en función de la carga prevista. Estas son recomendaciones generales que pueden variar según la especificidad de su uso de Keycloak y la configuración de la JVM.

Escenario de carga	Usuarios activos (simultáneos)	RPS (solicitudes por segundo)	vCPU	RAM (GB)	Disco (NVMe/SSD)	Costo estimado de VPS (Valebyte.com)
Desarrollo/Prueba/Mínima	Hasta 20	Hasta 5	2	2-4	40 GB NVMe	$5 - $10/mes
Pequeña empresa/Startup	50 - 200	10 - 30	2-4	4-8	60-80 GB NVMe	$10 - $25/mes
Mediana empresa/Proyecto en crecimiento	200 - 1000	30 - 100	4-8	8-16	100-200 GB NVMe	$25 - $60/mes
Gran empresa/Alta carga	1000 - 5000+	100 - 300+	8-16+	16-32+	200-500 GB NVMe	$60 - $150+/mes

Consideraciones adicionales:

• Alta disponibilidad: Para sistemas críticos, considere una implementación en clúster de Keycloak en varios VPS con un balanceador de carga.
• Base de datos separada: Con una carga muy alta o para garantizar una mayor fiabilidad, la base de datos PostgreSQL se puede mover a un VPS separado o utilizar un servicio de base de datos administrado.
• Red: Asegúrese de que su proveedor de VPS ofrezca una infraestructura de red estable y rápida.
• VPS autogestionado: La gestión de Keycloak en un servidor requiere ciertas habilidades de administración de sistemas. Si prefiere el control total y está dispuesto a mantenerlo usted mismo, un VPS autogestionado es su elección.

Estas recomendaciones le ayudarán a tomar una decisión informada al alquilar un Keycloak VPS que satisfaga sus necesidades actuales y futuras.

Posibles problemas y sus soluciones al trabajar con Keycloak en un VPS

Incluso con una instalación y configuración cuidadosas, pueden surgir problemas al trabajar con Keycloak en un VPS. Conocer los errores comunes y cómo solucionarlos le ayudará a restaurar rápidamente el funcionamiento del sistema.

Errores comunes al iniciar y acceder

1. Keycloak no se inicia / Error de conexión a la BD:
   • Causa: Credenciales de la base de datos incorrectas, la base de datos no está iniciada, problemas de red entre Keycloak y la BD.
   • Solución: Verifique los logs del contenedor de Keycloak (docker compose logs keycloak) y del contenedor de la BD (docker compose logs db). Asegúrese de que KC_DB_URL, KC_DB_USERNAME, KC_DB_PASSWORD en docker-compose.yml coincidan con la configuración de PostgreSQL. Verifique el estado del contenedor de la BD (docker compose ps) y su healthcheck.
2. El acceso a Keycloak por dominio no funciona (404 Not Found, 502 Bad Gateway):
   • Causa: Configuración incorrecta de Nginx/Caddy, registros DNS que no apuntan al VPS, el firewall bloquea los puertos.
   • Solución: Asegúrese de que el registro DNS (registro A para auth.yourdomain.com) apunte a la IP de su VPS. Verifique la configuración de Nginx/Caddy (sudo nginx -t, sudo caddy validate) y reinícielos. Asegúrese de que los puertos 80 y 443 estén abiertos en el firewall del VPS (sudo ufw status). Verifique que el contenedor de Keycloak esté escuchando en el puerto 8080.
3. Problemas con HTTPS / Certificado SSL no válido:
   • Causa: Certbot no pudo obtener el certificado, el dominio no se resuelve, configuración incorrecta de Nginx/Caddy para SSL.
   • Solución: Asegúrese de que su dominio apunte correctamente a la IP del VPS y sea accesible por el puerto 80 (Certbot lo usa para la verificación). Intente volver a emitir el certificado (sudo certbot --nginx -d auth.yourdomain.com). Verifique la configuración de Nginx/Caddy en busca de errores.
4. Keycloak devuelve un error "Invalid redirect URI" o "Invalid parameter: redirect_uri":
   • Causa: KC_HOSTNAME configurado incorrectamente en docker-compose.yml o "Valid Redirect URIs" incorrectamente especificados en la configuración del cliente en Keycloak.
   • Solución: Asegúrese de que KC_HOSTNAME coincida con el dominio por el cual Keycloak es accesible externamente (por ejemplo, auth.yourdomain.com). En la consola de administración de Keycloak, para cada cliente, vaya a la sección "Clients" -> "Su cliente" -> "Settings" y agregue todas las URL de redirección correctas en el campo "Valid Redirect URIs". Por ejemplo, https://your_app.com/*.
5. Funcionamiento lento de Keycloak:
   • Causa: Falta de recursos del VPS (CPU, RAM, IOPS), configuraciones de JVM no optimizadas, consultas ineficientes a la BD.
   • Solución: Verifique la utilización de recursos del VPS con herramientas de monitoreo (por ejemplo, Netdata). Considere actualizar el VPS a un plan más potente. Aumente la memoria JVM asignada (JAVA_OPTS: -Xmx4g en docker-compose.yml). Optimice la configuración de caché de Keycloak.

Optimización del rendimiento: consejos y trucos

• Aumente el tamaño del Heap de la JVM: Keycloak, al ser una aplicación Java, se beneficia de una cantidad suficiente de memoria. Agregue a la sección environment para el servicio keycloak en docker-compose.yml:

  JAVA_OPTS: "-Xmx4096m -Xms2048m"

  (donde 4096m = 4GB, 2048m = 2GB. Ajuste según la RAM disponible en su VPS).
• Habilite el almacenamiento en caché: Asegúrese de que el almacenamiento en caché de Keycloak esté activo. Por defecto, está configurado de manera razonable, pero si es necesario, se puede ajustar finamente a través de JGroups.
• Utilice discos NVMe: Para la base de datos y los datos de Keycloak, los discos NVMe proporcionan un rendimiento significativamente mayor en comparación con los SSD o HDD normales, lo cual es crucial para operaciones rápidas de lectura/escritura.
• Optimice la base de datos: Ejecute regularmente VACUUM ANALYZE para PostgreSQL para mantener el rendimiento de las consultas. Considere la indexación de campos de uso frecuente.
• Deshabilite funciones innecesarias: Si no utiliza algunas funciones de Keycloak (por ejemplo, federación, inicios de sesión sociales), deshabilitarlas puede reducir ligeramente el consumo de recursos.
• Monitoreo y perfilado: Utilice herramientas de monitoreo (como Netdata) para identificar cuellos de botella. Para un análisis profundo del rendimiento de una aplicación Java, puede usar el monitoreo JMX o perfiladores.
• Escalabilidad: Con una carga muy alta, considere la escalabilidad horizontal de Keycloak (varias instancias detrás de un balanceador de carga) y la externalización de la base de datos a un servidor de alto rendimiento separado o un servicio administrado.

El mantenimiento regular, el monitoreo y la optimización oportuna le ayudarán a mantener Keycloak en funcionamiento y a garantizar un alto rendimiento de su sistema de autenticación.

Conclusiones

La instalación y configuración de Keycloak en un VPS utilizando Docker Compose es una solución potente y rentable para la gestión centralizada de identidad y acceso. Obtiene control total sobre su infraestructura IAM, flexibilidad en la configuración y escalabilidad, lo que convierte a Keycloak self-hosted en un VPS en la elección ideal para la mayoría de los proyectos.

La elección de una configuración óptima de Keycloak VPS, las copias de seguridad regulares y el monitoreo activo son factores clave para el éxito. Valebyte.com ofrece servidores VPS fiables con discos NVMe y configuraciones flexibles, ideales para implementar Keycloak de cualquier escala, desde un entorno de prueba hasta un entorno de producción de alta carga.