Configuració de Keycloak v26 amb Nginx Reverse Proxy a Docker: resolució de problemes de la consola a diversos regnes

Superació dels errors de la consola Keycloak amb Nginx i Docker

Configurar Keycloak en un contenidor Docker amb un proxy inversor Nginx pot ser una configuració potent per gestionar l'accés segur, però no ve sense problemes. 🐳 Quan es migren bases de dades Keycloak o es gestionen diversos àmbits, sovint poden sorgir errors inesperats, creant confusió per als administradors.

Aquest escenari descriu la migració de Keycloak v19.0.2 a Keycloak v26, durant la qual va aparèixer un "No es pot determinar el missatge d'error" a tots els àmbits després de la sessió. El seguiment del problema mitjançant els registres d'error Nginx i Keycloak va mostrar una sol·licitud HTTP fallida.

En configuracions similars, un servidor intermediari mal configurat o una capa de xarxa pot desencadenar errors de "502 passarel·la dolenta", normalment a causa de problemes en com Nginx o Docker encaminen les sol·licituds a Keycloak. Aquest problema pot requerir ajustaments en la configuració del servidor intermediari, les variables d'entorn o les configuracions SSL per garantir que Keycloak funcioni perfectament.

En aquesta guia, explicarem possibles solucions per solucionar aquest problema a Keycloak. Revisarem les configuracions de les claus, analitzarem registres d'errors i explorarem configuracions específiques que poden ajudar a estabilitzar Keycloak dins d'una configuració de Docker-Nginx. Al final, tindreu informació sobre com resoldre aquests problemes i garantir un accés fluid i ininterromput a la consola d'administració.

Desglossament detallat de la configuració de Keycloak i Nginx

Els scripts que hem desenvolupat per configurar Keycloak darrere d'un servidor intermediari invers Nginx tenen un paper fonamental en l'encaminament i la gestió de l'accés segur a la consola d'administració de Keycloak. El fitxer de configuració de Nginx, per exemple, especifica un riu amunt bloc que defineix l'adreça IP i el port del backend de Keycloak, permetent a Nginx dirigir les sol·licituds amb precisió. Això és essencial per als escenaris en què el servei Keycloak opera en un segment de xarxa o contenidor Docker diferent. Mitjançant l'ús de directives de proxy com ara proxy_pass, permetem que Nginx actuï com a intermediari, gestionant sol·licituds externes i reenviant-les al punt final de servei intern de Keycloak. Aquesta configuració es veu habitualment en entorns de producció on els servidors intermediaris inversos són necessaris per a l'equilibri de càrrega i l'accés segur.

Dins de la configuració de Nginx, s'estableixen diverses capçaleres proxy_set_header ordres per garantir que Keycloak rebi tota la informació del client amb precisió. Per exemple, X-Real-IP i X-Forwarded-Proto s'utilitzen per passar la IP del client i el protocol de sol·licitud original. Aquesta informació és essencial perquè Keycloak l'utilitza per generar URL de redirecció precisos i gestionar polítiques de seguretat. Un problema comú en aquestes configuracions és la falta de capçaleres, cosa que pot provocar errors quan Keycloak intenta autenticar usuaris o validar dominis. En definir explícitament aquestes capçaleres, els administradors asseguren que Keycloak rep el context que necessita per processar les sol·licituds correctament. Aquest enfocament millora tant la seguretat com la coherència en com es gestionen les sol·licituds.

El fitxer Docker Compose que hem creat per a Keycloak simplifica el desplegament mitjançant un fitxer_env per a totes les variables d'entorn. Això permet que el contenidor Docker carregui configuracions com ara credencials de base de dades, nom d'amfitrió de Keycloak i camins relatius, fent-lo més segur i adaptable. L'ús d'un fitxer d'entorn també és pràctic perquè desacobla la informació sensible del fitxer Docker Compose, evitant els valors codificats. Com a resultat, canviar de bases de dades o modificar les credencials d'accés es fa sense problemes, cosa que és especialment útil en entorns dinàmics on els serveis s'actualitzen amb freqüència. A l'exemple, la variable d'entorn KC_PROXY_HEADERS establerta a "xforwarded" garanteix que Keycloak entengui que hi ha darrere d'un servidor intermediari, fent ajustos en la generació d'URL i la gestió de sessions en conseqüència.

A més de la configuració, hem proporcionat un Bash script que serveix com a simple comprovació de salut per verificar la disponibilitat de Keycloak. El guió utilitza rínxol per realitzar una sol·licitud HTTP al punt final de Keycloak i comprovar si el codi d'estat és igual a 200, indicant que el servei està operatiu. En cas d'error, l'script reinicia el contenidor Nginx, oferint una forma de recuperació automatitzada. Aquesta configuració és ideal per a entorns de producció on el temps d'activitat és crític, ja que permet que el servei s'autocura si es produeixen problemes de connexió. Provar scripts com aquest, juntament amb la prova d'unitat basada en Python per a l'accessibilitat dels punts finals, reforcen l'estabilitat del sistema, donant tranquil·litat als administradors sabent que la configuració notificarà o corregeix els problemes de manera proactiva. Aquest enfocament proactiu de la gestió és vital per minimitzar el temps d'inactivitat i garantir un accés perfecte a Keycloak consola d'administració.

upstream sso-mydomain-com {
    server 10.10.0.89:8080;
}
server {
    listen 443 ssl;
    server_name sso.mydomain.com;
    location / {
        proxy_pass http://sso-mydomain-com/;
        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;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}
server {
    listen 8443 ssl;
    server_name sso.mydomain.com;
    error_log /usr/local/nginx/logs/sso_err.log debug;
    location / {
        proxy_pass http://sso-mydomain-com/;
        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;
    }
    ssl_certificate /etc/nginx/ssl/sso.mydomain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/sso.mydomain.com/privkey.pem;
}

version: '3.9'
services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.0
    env_file:
      - .env
    ports:
      - "8080:8080"
    volumes:
      - /opt/keycloak/themes:/opt/keycloak/themes
      - /etc/localtime:/etc/localtime
    privileged: true
    command: start

import requests
def test_whoami_endpoint():
    url = "https://sso.mydomain.com:8443/auth/admin/master/console/whoami?currentRealm=master"
    headers = {"Content-Type": "application/json"}
    try:
        response = requests.get(url, headers=headers, verify=True)
        assert response.status_code == 200, "Expected 200 OK, got {}".format(response.status_code)
        print("Test passed: whoami endpoint accessible")
    except requests.ConnectionError:
        print("Connection error: Check Nginx reverse proxy and Keycloak availability")
    except AssertionError as e:
        print("Assertion error:", e)
# Run the test
test_whoami_endpoint()

#!/bin/bash
# Check if Keycloak is reachable via the /whoami endpoint
URL="http://10.10.0.89:8080/auth/admin/master/console/whoami"
STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" $URL)
if [ "$STATUS_CODE" -ne 200 ]; then
    echo "Keycloak endpoint unavailable, restarting Nginx..."
    docker restart nginx
else
    echo "Keycloak endpoint is healthy."
fi

Optimització de Keycloak per a operacions de servidor intermediari invers segur i sense problemes

Quan es configura Keycloak darrere d'un servidor intermediari invers com Nginx, diverses consideracions addicionals poden ajudar a garantir que la configuració sigui segura, eficient i estable. Un aspecte crucial és la terminació SSL: manejar HTTPS a la capa Nginx. Com que Keycloak normalment escolta a HTTP dins de Docker, Nginx pot actuar com a punt final SSL, descarregant el xifratge i reduint la càrrega de recursos a Keycloak. Aquesta configuració permet a Nginx comunicar-se amb Keycloak a través d'HTTP mentre manté l'accés HTTPS segur per als usuaris finals. A més, els certificats SSL només s'emmagatzemen a Nginx, la qual cosa simplifica la gestió de certificats. Eines automatitzades com Let's Encrypt poden agilitzar la renovació, especialment amb scripts que tornen a carregar Nginx a mesura que s'actualitzen els certificats.

Un altre factor important és l'equilibri de càrrega i l'escala. Per exemple, utilitzant les configuracions de xarxa de Docker, els administradors poden crear un grup de servidors aigües amunt a Nginx que inclogui diversos contenidors Keycloak, millorant la distribució de càrrega i la disponibilitat. El proxy_pass La directiva apunta a aquest grup, permetent a Nginx dirigir les sol·licituds a diverses instàncies de Keycloak. Aquest enfocament és beneficiós en entorns de gran trànsit, ja que evita que qualsevol instància sigui desbordada. A més, la persistència de la sessió, també anomenada sessions adhesives, garanteix que els usuaris romanguin connectats a la mateixa instància, evitant problemes d'autenticació. Les comprovacions de salut es poden automatitzar mitjançant scripts Nginx o Docker, supervisant la disponibilitat de Keycloak i reiniciant les instàncies si es produeixen errors. 🛠️

Finalment, aprofitar les mètriques i els registres integrats de Keycloak és vital per mantenir i solucionar problemes del sistema. Keycloak pot generar registres detallats per a cada sol·licitud, que, quan es combinen amb els registres d'accés de Nginx, creen una pista d'auditoria completa. Eines de monitorització com Prometheus i Grafana poden visualitzar les mètriques de rendiment de Keycloak, alertant els administradors d'anomalies abans que afectin els usuaris. A Nginx, configuració error_log a debug nivell durant la configuració captura informació detallada per diagnosticar problemes de configuració o de xarxa. En conjunt, aquestes estratègies garanteixen un desplegament de Keycloak més resistent i segur, cosa que el converteix en una solució ideal per a l'autenticació de nivell empresarial darrere d'un servidor intermediari invers.