Manual de Implementación de Keycloak en Alta Disponibilidad (HA)

rokitoh Cluster, Keycloak, NGINX, PostgreSQL, UNIX - *BSD - GNU/Linux

Introducción

Este manual te guiará paso a paso en la implementación de un servidor de Keycloak en alta disponibilidad (HA), una solución de gestión de identidades y acceso (IAM) de código abierto. Keycloak se configurará para funcionar como un clúster, asegurando que el servicio permanezca disponible incluso si uno de los nodos falla.

Para lograr la persistencia de datos y la robustez del sistema, utilizaremos una base de datos PostgreSQL en alta disponibilidad que ya habremos configurado siguiendo los manuales de Red Órbita:

Este enfoque garantiza que tanto la capa de aplicación (Keycloak) como la de datos (PostgreSQL) sean resilientes y escalables.

1. Preparación del Sistema

Antes de instalar Keycloak, es crucial preparar tu servidor. Asegúrate de tener un sistema operativo Linux basado en Debian o Ubuntu.

Actualizar repositorios y paquetes

Comienza por actualizar los repositorios de software y los paquetes de tu sistema para asegurarte de que todo esté al día.

# Actualizar repositorios y paquetes
sudo apt update && sudo apt upgrade -y

Instalar dependencias

Instala las dependencias necesarias para que Keycloak y el Java Development Kit (JDK) funcionen correctamente.

sudo apt install -y unzip wget openjdk-17-jdk openssl

2. Creación del Usuario de Keycloak

Por razones de seguridad, es una buena práctica ejecutar Keycloak con un usuario dedicado en lugar de root.

Crea un usuario del sistema llamado keycloak, su directorio principal y asigna los permisos adecuados.

sudo useradd -r -s /bin/bash -d /opt/keycloak keycloak
sudo mkdir -p /opt/keycloak
sudo chown keycloak:keycloak /opt/keycloak

3. Descarga e Instalación de Keycloak

Ahora, descarga la última versión de Keycloak y muévela a su directorio de instalación.

Descarga el archivo ZIP de Keycloak, descomprímelo y copia su contenido al directorio /opt/keycloak. Finalmente, asegúrate de que el usuario keycloak sea el propietario de todos los archivos.

 

cd /tmp
wget https://github.com/keycloak/keycloak/releases/download/26.3.3/keycloak-26.3.3.zip
unzip keycloak-26.3.3.zip
sudo mv keycloak-26.3.3/* /opt/keycloak/
sudo chown -R keycloak:keycloak /opt/keycloak

4. Configuración de la Base de Datos PostgreSQL

En este paso, configurarás la base de datos PostgreSQL que creaste previamente para que Keycloak pueda almacenar sus datos.

Accede al cliente de PostgreSQL con el usuario postgres.

sudo -u postgres psql

Una vez dentro del cliente, ejecuta los siguientes comandos para crear una base de datos, un usuario dedicado y asignarle los permisos necesarios.

-- Crear base de datos y usuario
CREATE DATABASE keycloak_vault;
CREATE USER keycloak_user WITH ENCRYPTED PASSWORD 'SecurePass123!';
GRANT ALL PRIVILEGES ON DATABASE keycloak_vault TO keycloak_user;

-- Dar permisos al esquema público
GRANT USAGE ON SCHEMA public TO keycloak_user;
GRANT CREATE ON SCHEMA public TO keycloak_user;

-- Alternativamente, dar todos los permisos sobre la base de datos
GRANT ALL PRIVILEGES ON DATABASE keycloak_vault TO keycloak_user;

-- Configurar propietario y permisos por defecto
ALTER SCHEMA public OWNER TO keycloak_user;
GRANT ALL ON SCHEMA public TO keycloak_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO keycloak_user;

5. Creación de Certificados HTTPS Autofirmados

Para asegurar la comunicación entre los nodos de Keycloak y los clientes, es esencial usar HTTPS. Generaremos certificados autofirmados para la configuración inicial.

Crea un directorio para los certificados y genera una clave privada y un certificado autofirmado con openssl.

sudo mkdir -p /opt/keycloak/certs
sudo chown keycloak:keycloak /opt/keycloak/certs
cd /opt/keycloak/certs

# Generar clave privada
sudo -u keycloak openssl genrsa -out key.pem 2048

# Generar certificado autofirmado
sudo -u keycloak openssl req -new -x509 -key key.pem -out cert.pem -days 365 \
  -subj "/C=ES/ST=Madrid/L=Madrid/O=Redorbita/OU=IT/CN=keycloak.local"

# Ajustar permisos
sudo chown keycloak:keycloak cert.pem key.pem
sudo chmod 600 cert.pem key.pem

6. Configuración de Keycloak (keycloak.conf)

Ahora, configura el archivo principal de Keycloak para que se conecte a la base de datos, configure los puertos y active el modo de clúster.

Edita el archivo de configuración.

sudo -u keycloak nano /opt/keycloak/conf/keycloak.conf

Añade el siguiente contenido, ajustando db-url con la IP VIP de tu clúster de PostgreSQL y cluster-node-name y frontend-url según tu entorno.

# Database
db=postgres
db-username=keycloak_user
db-password=SecurePass123!
db-url=jdbc:postgresql://192.168.1.217:5432/keycloak_vault
db-pool-min-size=5
db-pool-max-size=20

# HTTP/HTTPS
http-enabled=true
http-port=8080
https-port=8443

# PROXY CONFIGURATION
proxy=xforwarded 
proxy-headers=xforwarded
hostname-url=https://keycloak.redorbita.local
hostname-admin-url=https://keycloak.redorbita.local
hostname-strict=false
hostname-strict-https=false
hostname-strict-backchannel=false

# HTTPS Certificates
https-certificate-file=/opt/keycloak/certs/cert.pem
https-certificate-key-file=/opt/keycloak/certs/key.pem

# Cookies
http-relative-path=/

# Clustering
cluster-stack=udp
cluster-node-name=srvlrokeycloak01
cluster-stack-udp-address=230.0.0.4
cluster-stack-udp-port=45700

# Logging para debug
log-level=INFO

7. Configuración del Servicio systemd

Para gestionar Keycloak como un servicio del sistema, crea un archivo de unidad systemd. Esto permitirá que Keycloak se inicie automáticamente al arrancar el servidor.

Crea y edita el archivo del servicio.

sudo vi /etc/systemd/system/keycloak.service

Añade el siguiente contenido. Las variables de entorno aquí anulan las del archivo keycloak.conf y son recomendadas para una gestión más sencilla del servicio.

[Unit]
Description=Keycloak Server
After=network.target

[Service]
Type=simple
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Crea el usuario de acceso a Keycloak

KEYCLOAK_PASSWORD=SecurePassword123!

sudo -E /opt/keycloak/bin/kc.sh bootstrap-admin user --username admin --password:env KEYCLOAK_PASSWORD

Recarga systemd y habilita e inicia el servicio Keycloak.

sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak

8. Verificación del Estado del Servicio

Verifica que Keycloak se esté ejecutando correctamente y sin errores.

sudo systemctl status keycloak
sudo journalctl -u keycloak -f

Si la instalación es correcta, verás una salida similar a esta:

Keycloak 26.3.3 on JVM (powered by Quarkus) started in ...s
Listening on: http://0.0.0.0:8080 and https://0.0.0.0:8443
Profile prod activated.

9. Acceso Inicial

Una vez que el servicio esté activo, podrás acceder a la interfaz de Keycloak a través de los puertos configurados.

  • HTTP: http://<IP_SERVIDOR>:8080
  • HTTPS: https://<IP_SERVIDOR>:8443 (aceptar certificado autofirmado en el navegador)

10. Configuración de NGINX como Proxy Inverso

Para gestionar el tráfico de forma más segura y flexible, instalaremos NGINX y lo configuraremos como un proxy inverso.

Instalar NGINX

sudo apt update
sudo apt install -y nginx

Creación de Certificado TLS

Aunque Keycloak ya tiene un certificado, es mejor usar uno dedicado para NGINX. Genera un certificado TLS autofirmado para tu dominio.

sudo mkdir -p /etc/nginx/certs
sudo openssl req -new -x509 -nodes -days 365 -out /etc/nginx/certs/keycloak.crt -keyout /etc/nginx/certs/keycloak.key \
  -subj "/C=ES/ST=Madrid/L=Madrid/O=RedOrbita/OU=IT/CN=keycloak.redorbita.local"
sudo chmod 600 /etc/nginx/certs/keycloak.*

Configurar Proxy Inverso

Crea el archivo de configuración de NGINX para Keycloa

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

Pega el siguiente contenido. NGINX redirigirá el tráfico HTTP al puerto 80 a HTTPS en el 443 y actuará como proxy para el servidor Keycloak, que escucha en el puerto 8080.

# Define el grupo de servidores Keycloak
upstream keycloak_cluster {
    server 192.168.1.212:8080;
    server 192.168.1.213:8080;
}

server {
    listen 443 ssl http2;
    server_name keycloak.redorbita.local;

    ssl_certificate /etc/nginx/certs/keycloak.crt;
    ssl_certificate_key /etc/nginx/certs/keycloak.key;

    location / {
        # Usar HTTP para comunicación interna
        proxy_pass http://keycloak_cluster;
        
        # Headers esenciales
        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;

        # WebSocket
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

11. Configuración de Alta Disponibilidad para Nginx con Keepalived

Para que el balanceador de carga sea un punto único de acceso y a prueba de fallos, utilizaremos Keepalived. Esta herramienta gestionará una IP Virtual (VIP) que siempre estará activa en uno de los dos nodos de Nginx (srvlrolb01 y srvlrolb02). Si el nodo principal falla, el nodo de respaldo tomará el control de la VIP.

11.1. Instalación de Keepalived

Instala Keepalived en ambos servidores de balanceo de carga: srvlrolb01 (maestro) y srvlrolb02 (respaldo).

sudo apt update
sudo apt install -y keepalived

11.2. Configuración en el Servidor Maestro (srvlrolb01)

Edita el archivo de configuración de Keepalived en el nodo maestro.

sudo vi /etc/keepalived/keepalived.conf

Pega el siguiente contenido. Está configuración establecerá este nodo como maestro

global_defs {
      router_id srvlrolb01
}

vrrp_instance VI_1 {
     state MASTER
     interface ens18
     virtual_router_id 51
     priority 101
     advert_int 1
	

authentication {
	auth_type PASS
	auth_pass 1111
}

virtual_ipaddress {
	192.168.1.209
	}
}
  • state MASTER: Este nodo será el primario.
  • priority 101: Una prioridad alta para asegurar que este nodo sea el maestro.
  • virtual_ipaddress: La dirección IP virtual que flotará entre los dos nodos.

11.3. Configuración en el Servidor de Respaldo (srvlrolb02)

Ahora, configura el nodo de respaldo. Edita el archivo de configuración de Keepalived en el segundo servidor.

sudo vi /etc/keepalived/keepalived.conf

Pega el siguiente contenido. La configuración es similar al maestro, pero con state BACKUP y una priority más baja.


global_defs {
   router_id srvlrolb02
}

vrrp_instance VI_1 {
    state BACKUP
    interface ens18
    virtual_router_id 51
    priority 100
    advert_int 1

    authentication {
        auth_type PASS
        auth_pass 1111
    }

    virtual_ipaddress {
        192.168.1.209
    }
}
  • state BACKUP: Este nodo será el de respaldo.
  • priority 100: Prioridad más baja que el maestro.

11.4. Habilitar y Arrancar Keepalived

sudo systemctl daemon-reload
sudo systemctl enable keepalived
sudo systemctl start keepalived

Una vez configurados ambos archivos, habilita y reinicia el servicio Keepalived en ambos servidores.

11.5. Verificación de la VIP

Verifica que la VIP se haya asignado al nodo maestro (srvlrolb01) ejecutando el siguiente comando.

ip a

Deberías ver la IP virtual (192.168.1.209) asociada a la interfaz de red.

Con esta configuración, tu clúster de Nginx ahora es redundante y el servicio de balanceo de carga estará protegido contra fallos de un solo punto.

Activar la Configuración y Reiniciar NGINX

Crea un enlace simbólico para activar la configuración y reinicia el servicio NGINX.

sudo ln -s /etc/nginx/sites-available/keycloak.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
sudo systemctl enable nginx

Acceso Keycloack

Accedemos desde el navegador a la URL configurada en Nginx (en este caso: https://keycloak.redorbita.local) y nos autenticamos utilizando las credenciales que generamos previamente.

:wq!

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *