Configuration de Keycloak v26 avec le proxy inverse Nginx dans Docker : résolution des problèmes de console dans divers domaines

Surmonter les erreurs de la console Keycloak avec Nginx et Docker

La configuration de Keycloak dans un conteneur Docker avec un proxy inverse Nginx peut être une configuration puissante pour gérer l'accès sécurisé, mais cela ne va pas sans défis. 🐳 Lors de la migration de bases de données Keycloak ou de la gestion de plusieurs domaines, des erreurs inattendues peuvent souvent survenir, créant une confusion pour les administrateurs.

Ce scénario décrit la migration de Keycloak v19.0.2 vers Keycloak v26, au cours de laquelle un message d'erreur « Impossible de déterminer » est apparu dans tous les domaines après la connexion. Le suivi du problème via les journaux Nginx et les journaux d'erreurs Keycloak a montré une requête HTTP ayant échoué.

Dans des configurations similaires, un proxy ou une couche réseau mal configuré peut déclencher des erreurs « 502 bad gateway », généralement dues à des problèmes dans la façon dont Nginx ou Docker achemine les requêtes vers Keycloak. Ce problème peut nécessiter des ajustements dans les paramètres de proxy, les variables d'environnement ou les configurations SSL pour garantir le fonctionnement transparent de Keycloak.

Dans ce guide, nous passerons en revue les solutions potentielles pour résoudre ce problème dans Keycloak. Nous examinerons les configurations clés, analyserons les journaux d'erreurs et explorerons les paramètres spécifiques qui peuvent aider à stabiliser Keycloak dans une configuration Docker-Nginx. À la fin, vous aurez des idées pour résoudre ces problèmes et garantir un accès fluide et ininterrompu à la console d'administration.

Répartition détaillée de la configuration Keycloak et Nginx

Les scripts que nous avons développés pour configurer Keycloak derrière un proxy inverse Nginx jouent un rôle essentiel dans le routage et la gestion de l'accès sécurisé à la console d'administration Keycloak. Le fichier de configuration Nginx, par exemple, spécifie un en amont bloc qui définit l’adresse IP et le port du backend de Keycloak, permettant à Nginx de diriger les requêtes avec précision. Ceci est essentiel pour les scénarios dans lesquels le service Keycloak fonctionne dans un segment de réseau ou un conteneur Docker différent. En utilisant des directives proxy telles que proxy_pass, nous permettons à Nginx d’agir en tant qu’intermédiaire, en traitant les demandes externes et en les transmettant au point de terminaison de service interne de Keycloak. Cette configuration est couramment observée dans les environnements de production où les proxys inverses sont nécessaires pour l'équilibrage de charge et l'accès sécurisé.

Dans la configuration Nginx, plusieurs en-têtes sont définis avec proxy_set_header commandes pour garantir que Keycloak reçoive toutes les informations client avec précision. Par exemple, X-Real-IP et Proto-X-Forwarded sont utilisés pour transmettre l’adresse IP du client et le protocole de demande d’origine. Ces informations sont essentielles car Keycloak les utilise pour générer des URL de redirection précises et gérer les politiques de sécurité. Un problème courant dans de telles configurations est l'absence d'en-têtes, ce qui peut entraîner des erreurs lorsque Keycloak tente d'authentifier les utilisateurs ou de valider des domaines. En définissant explicitement ces en-têtes, les administrateurs garantissent que Keycloak reçoit le contexte dont il a besoin pour traiter correctement les demandes. Cette approche améliore à la fois la sécurité et la cohérence dans la façon dont les demandes sont gérées.

Le fichier Docker Compose que nous avons créé pour Keycloak simplifie le déploiement en utilisant un fichier_env pour toutes les variables d'environnement. Cela permet au conteneur Docker de charger des configurations telles que les informations d'identification de la base de données, le nom d'hôte Keycloak et les chemins relatifs, ce qui le rend plus sécurisé et adaptable. L'utilisation d'un fichier d'environnement est également pratique car elle dissocie les informations sensibles du fichier Docker Compose, évitant ainsi les valeurs codées en dur. En conséquence, le changement de base de données ou la modification des informations d'identification devient transparent, ce qui est particulièrement utile dans les environnements dynamiques où les services sont fréquemment mis à jour. Dans l'exemple, la variable d'environnement KC_PROXY_HEADERS définie sur "xforwarded" garantit que Keycloak comprend qu'il se trouve derrière un proxy, effectuant des ajustements dans la génération d'URL et la gestion de session en conséquence.

En plus de la configuration, nous avons fourni un Frapper script qui sert de simple contrôle de santé pour vérifier la disponibilité de Keycloak. Le script utilise boucle pour effectuer une requête HTTP au point de terminaison Keycloak et vérifie si le code d'état est égal à 200, indiquant que le service est opérationnel. En cas d'échec, le script redémarre le conteneur Nginx, offrant une forme de récupération automatisée. Cette configuration est idéale pour les environnements de production où la disponibilité est critique, car elle permet au service de s'auto-réparer si des problèmes de connexion surviennent. Des scripts de test comme celui-ci, ainsi que le test unitaire basé sur Python pour l'accessibilité des points de terminaison, renforcent la stabilité du système, offrant aux administrateurs une tranquillité d'esprit sachant que l'installation notifiera ou corrigera les problèmes de manière proactive. Cette approche proactive de la gestion est essentielle pour minimiser les temps d'arrêt et garantir un accès transparent aux ressources de Keycloak. console d'administration.

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

Optimisation de Keycloak pour des opérations de proxy inverse sécurisées et transparentes

Lors de la configuration de Keycloak derrière un proxy inverse comme Nginx, plusieurs considérations supplémentaires peuvent contribuer à garantir que la configuration est sécurisée, performante et stable. Un aspect crucial est la terminaison SSL : la gestion du HTTPS au niveau de la couche Nginx. Étant donné que Keycloak écoute généralement HTTP dans Docker, Nginx peut agir comme point de terminaison SSL, déchargeant le cryptage et réduisant la charge des ressources sur Keycloak. Cette configuration permet à Nginx de communiquer avec Keycloak via HTTP tout en conservant un accès HTTPS sécurisé pour les utilisateurs finaux. De plus, les certificats SSL sont stockés uniquement sur Nginx, ce qui simplifie la gestion des certificats. Des outils automatisés comme Let's Encrypt peuvent rationaliser le renouvellement, en particulier avec des scripts qui rechargent Nginx lors de la mise à jour des certificats.

Un autre facteur important est l’équilibrage et la mise à l’échelle de la charge. Par exemple, à l'aide des configurations réseau de Docker, les administrateurs peuvent créer un pool de serveurs en amont dans Nginx qui comprend plusieurs conteneurs Keycloak, améliorant ainsi la répartition de la charge et la disponibilité. Le proxy_pass La directive pointe vers ce pool, permettant à Nginx d'acheminer les requêtes sur plusieurs instances Keycloak. Cette approche est bénéfique dans les environnements à fort trafic, car elle évite qu’une seule instance soit submergée. De plus, la persistance de session, également appelée sessions persistantes, garantit que les utilisateurs restent connectés à la même instance, évitant ainsi les problèmes d'authentification. Les vérifications de l'état peuvent être automatisées à l'aide de scripts Nginx ou Docker, en surveillant la disponibilité de Keycloak et en redémarrant les instances en cas de panne. 🛠️

Enfin, l’exploitation des métriques et des journaux intégrés de Keycloak est essentielle pour la maintenance et le dépannage du système. Keycloak peut générer des journaux détaillés pour chaque requête qui, lorsqu'ils sont associés aux journaux d'accès de Nginx, créent une piste d'audit complète. Les outils de surveillance tels que Prometheus et Grafana peuvent visualiser les mesures de performances de Keycloak, alertant les administrateurs des anomalies avant qu'elles n'affectent les utilisateurs. Dans Nginx, paramètre journal_erreur à debug Le niveau lors de l'installation capture des informations détaillées pour diagnostiquer les problèmes de configuration ou de réseau. Ensemble, ces stratégies garantissent un déploiement Keycloak plus résilient et sécurisé, ce qui en fait une solution idéale pour l'authentification de niveau entreprise derrière un proxy inverse.