🔐 Keycloak 26 : Guide Complet pour Créer un Cluster Haute Disponibilité avec Docker et JDBC_PING

🔴 Niveau : Avancé | ⏱️ Lecture : 40 min | 🛠️ Mise en œuvre : 1-2 heures

📚 Prérequis

1 serveur Linux (Debian 12/13 ou Ubuntu 22.04/24.04 LTS)
Docker et Docker Compose installés
Base de données PostgreSQL accessible (voir notre tutoriel PostgreSQL 17 HA)
Accès root ou sudo sur le serveur
(Optionnel) Nom de domaine + certificat SSL pour la production

Keycloak est la solution IAM (Identity and Access Management) open source de référence. Dans ce tutoriel complet, nous allons déployer un cluster Keycloak 26 en haute disponibilité avec Docker Compose, utilisant JDBC_PING pour la découverte automatique des nœuds et une base PostgreSQL externe.

Cette architecture est prête pour la production : failover automatique, sessions distribuées, et scaling horizontal simple.

🏗️ Architecture du Cluster

Notre cluster Keycloak sera composé de 2 réplicas (ou plus) avec une base PostgreSQL externe :

📊 Rôle de chaque composant

Keycloak 26 : Serveur d’authentification SSO avec support OIDC, SAML 2.0, OAuth 2.0
JDBC_PING : Protocole de découverte des nœuds du cluster via la base de données (pas de multicast requis)
PostgreSQL : Base de données pour stocker la configuration, les utilisateurs et la table de découverte cluster
Reverse Proxy : Terminaison SSL, load balancing et routing vers les nœuds Keycloak

🔌 Ports utilisés

Port	Service	Description
8080	Keycloak HTTP	Interface web et API REST
8443	Keycloak HTTPS	Interface sécurisée (si configuré)
9000	Keycloak Management	Health checks et métriques
5432	PostgreSQL	Base de données
443	Reverse Proxy	Point d’entrée HTTPS public

🔄 Pourquoi JDBC_PING ?

Keycloak 26 utilise par défaut JDBC_PING pour la découverte des nœuds en mode production. Cette méthode présente plusieurs avantages :

✅ Pas de multicast : Fonctionne dans tous les environnements (cloud, Docker, Kubernetes)
✅ Simple : Utilise la base de données existante comme registre
✅ Fiable : Chaque nœud s’enregistre dans une table PostgreSQL
✅ Failover automatique : Un nœud qui tombe est détecté et retiré

⚙️ Étape 1 : Préparation du Serveur

Commençons par préparer notre serveur et installer Docker.

1.1 Mise à jour du système

1.2 Installation de Docker

Important : Déconnectez-vous et reconnectez-vous pour que les changements de groupe prennent effet.

🐘 Étape 2 : Configuration de PostgreSQL

Keycloak a besoin d’une base PostgreSQL. Si vous n’avez pas encore de cluster PostgreSQL, consultez notre tutoriel pour déployer un cluster PostgreSQL 17 HA complet ou utilisez notre rôle Ansible qui le déploie pour vous en 5 minutes ci-dessous.

Découvrir le rôle postgres_ha

2.1 Création de la base et de l’utilisateur

Connectez-vous à votre serveur PostgreSQL et exécutez :

2.2 Configuration de pg_hba.conf

Ajoutez une règle pour autoriser les connexions depuis votre serveur Keycloak :

Rechargez la configuration PostgreSQL après modification.

🐳 Étape 3 : Image Keycloak Optimisée

Pour la production, nous allons créer une image Docker optimisée de Keycloak. Cette image pré-compile les configurations et réduit significativement le temps de démarrage.

3.1 Création de l’arborescence

3.2 Dockerfile multi-stage

Créez le fichier Dockerfile :

Ce Dockerfile utilise un build multi-stage :

Stage 1 (builder) : Compile Keycloak avec les options de production (PostgreSQL, health, metrics)
Stage 2 : Copie uniquement les fichiers optimisés dans l’image finale

📦 Étape 4 : Configuration Docker Compose

Créez le fichier docker-compose.yml complet :

📝 Explication des variables d’environnement

Variable	Description
`KEYCLOAK_ADMIN`	Nom d’utilisateur administrateur initial
`KEYCLOAK_ADMIN_PASSWORD`	Mot de passe administrateur initial (changer en prod!)
`KC_DB`	Type de base de données (postgres)
`KC_DB_URL`	URL JDBC de connexion PostgreSQL
`KC_DB_USERNAME`	Utilisateur PostgreSQL
`KC_DB_PASSWORD`	Mot de passe PostgreSQL
`KC_PROXY_HEADERS`	Headers de proxy à faire confiance (xforwarded)
`KC_HTTP_ENABLED`	Activer HTTP (requis derrière un reverse proxy SSL)
`KC_HEALTH_ENABLED`	Activer les endpoints /health/*

🚀 Étape 5 : Démarrage du Cluster

5.1 Build de l’image optimisée

5.2 Lancement du cluster

Attendez de voir le message Keycloak 26.0 on JVM (powered by Quarkus) started sur les deux réplicas.

5.3 Vérification du cluster

5.4 Accès à la console d’administration

Ouvrez votre navigateur à l’adresse : http://<IP_SERVEUR>:8080/admin/

Utilisateur : admin
Mot de passe : VotreMotDePasseAdmin (celui configuré dans docker-compose.yml)

🔒 Étape 6 : Reverse Proxy Nginx (HTTPS)

En production, vous devez placer un reverse proxy devant Keycloak pour la terminaison SSL.

6.1 Installation de Nginx

6.2 Configuration Nginx

Créez le fichier /etc/nginx/sites-available/keycloak :

6.3 Activation et test

6.4 Mise à jour docker-compose pour hostname fixe

Modifiez le docker-compose.yml pour utiliser l’hostname de production :

Puis redémarrez le cluster :

✅ Étape 7 : Tests et Validation

7.1 Création d’un Realm de test

Dans la console admin (https://auth.example.com/admin/) :

Cliquez sur le menu déroulant « master » → Create Realm
Entrez le nom : test
Cliquez Create

7.2 Création d’un utilisateur

Menu Users → Add user
Username : testuser
Email : test@example.com
Email verified : On
Cliquez Create
Onglet Credentials → Set password
Désactivez Temporary et définissez un mot de passe

7.3 Création d’un client OIDC

Menu Clients → Create client
Client ID : test-app
Client type : OpenID Connect
Next → Laissez les options par défaut
Next → Valid redirect URIs : * (pour les tests uniquement!)
Save

7.4 Test d’authentification OIDC

7.5 Vérifier le clustering

🔧 Troubleshooting

Problème : Keycloak ne démarre pas

Problème : Les nœuds ne forment pas de cluster

Problème : Erreur « Invalid redirect URI »

Dans le client OIDC, ajoutez l’URI de redirection correcte dans Valid redirect URIs et Valid post logout redirect URIs.

Problème : Sessions non partagées entre nœuds

Vérifiez que le cluster est bien formé. Si les nœuds ne se voient pas, les sessions ne seront pas répliquées.

🔧 Commandes Utiles

🚀 Conclusion : Automatisez avec Ansible !

Vous venez de déployer manuellement un cluster Keycloak HA complet. Cette configuration vous offre :

✅ Haute disponibilité avec failover automatique
✅ Sessions distribuées entre les nœuds
✅ Scaling horizontal simple avec Docker Compose
✅ Image optimisée pour des démarrages rapides
✅ JDBC_PING : Fonctionne partout sans multicast

Cependant, ce processus manuel est long, répétitif et source d’erreurs. Pour des déploiements en production, nous recommandons fortement d’automatiser avec Ansible.

DevOps Store propose des rôles Ansible professionnels, testés et documentés pour automatiser votre infrastructure. Notre rôle keycloak_ha déploie cette architecture complète en quelques minutes :

🔄 Idempotent : Exécutez-le autant de fois que nécessaire
⚙️ Configurable : Réplicas, mémoire JVM, hostname personnalisables
✅ Testé : Validé avec Molecule sur Debian 12/13 et Ubuntu 22.04/24.04
📚 Documenté : Guides Day-1 et Day-2 inclus
🔐 Sécurisé : Supporte Ansible Vault pour les secrets

Découvrir le rôle keycloak_ha

📖 Glossaire

Keycloak : Solution IAM open source développée par Red Hat, standard de facto pour le SSO
OIDC : OpenID Connect, protocole d’authentification basé sur OAuth 2.0
SAML : Security Assertion Markup Language, protocole SSO basé sur XML
JDBC_PING : Méthode de découverte des nœuds cluster via une table en base de données
Realm : Espace de noms isolé dans Keycloak contenant utilisateurs, clients et configurations
Client : Application enregistrée dans Keycloak pour l’authentification
Infinispan : Cache distribué utilisé par Keycloak pour les sessions et tokens

Ce tutoriel vous a été utile ? Partagez-le avec vos collègues DevOps !