Keycloak production : déploiement Hetzner + Postgres (2026)

Introduction

Keycloak s’est imposé comme le référentiel de facto en matière de gestion des identités et des accès (IAM) dans le monde open-source enterprise. En 2026, le projet — désormais entièrement porté par la fondation Cloud Native Computing Foundation (CNCF) sous l’égide de Red Hat — tourne exclusivement sur Quarkus, le framework Java natif cloud qui a remplacé l’historique WildFly depuis la version 17. Cette bascule n’est pas anodine : elle a divisé par deux l’empreinte mémoire au démarrage et réduit le temps de boot de plusieurs minutes à quelques secondes, rendant Keycloak enfin raisonnable à héberger sur un VPS d’entrée de gamme.

Ce tutoriel vous guide pas à pas pour installer Keycloak v26 en production réelle sur un serveur Hetzner CX31 (4 vCPU, 8 Go RAM), en utilisant PostgreSQL comme base de données persistante, Traefik comme reverse proxy avec TLS automatique, et en activant le MFA par défaut (WebAuthn + TOTP). À l’issue de ce guide — comptez environ 50 minutes la première fois — vous disposerez d’un serveur d’authentification centralisée capable de fédérer les comptes de vos collaborateurs, de connecter ERPNext, Nextcloud et n’importe quelle application compatible OIDC, et de résister à une panne de session grâce aux sauvegardes Postgres quotidiennes.

Ce guide cible les équipes techniques de PME ouest-africaines qui souhaitent sortir de la dépendance aux fournisseurs d’identité cloud (Google Workspace, Microsoft Entra ID) et reprendre le contrôle de leurs données d’authentification. Toutes les commandes ont été validées sur Ubuntu 22.04 LTS.

Prérequis

• Serveur : Hetzner Cloud CX31 (4 vCPU, 8 Go RAM, 80 Go SSD NVMe) — minimum absolu pour Keycloak en production. Le CX21 (4 Go) fonctionne en dev mais swappe en production avec plusieurs realms actifs.
• OS : Ubuntu 22.04 LTS (image Hetzner officielle)
• Docker Engine ≥ 24.x et Docker Compose v2 installés (docker compose sans tiret)
• Domaine DNS : un sous-domaine pointant vers l’IP du serveur, ex. auth.monentreprise.com (TTL 60 s minimum pour Traefik)
• Ports ouverts : 80/TCP et 443/TCP dans le firewall Hetzner Cloud
• Niveau : administrateur système intermédiaire — familiarité avec Docker, les variables d’environnement et les bases de la ligne de commande Linux
• Temps estimé : 45 à 55 minutes

Étape 1 — Quarkus vs WildFly : comprendre le positionnement de Keycloak v26

Avant de taper la première commande, il est utile de comprendre ce que signifie concrètement la migration de WildFly vers Quarkus pour votre infrastructure. WildFly était un serveur d’applications Java EE complet, généraliste, conçu à une époque où les serveurs physiques duraient dix ans et où la mémoire n’était pas un coût variable. Il démarrait en 2 à 3 minutes, consommait 1,2 à 1,5 Go de RAM au repos, et son modèle de configuration reposait sur un XML volumineux (standalone.xml) que personne ne lisait intégralement.

Quarkus est une rupture de paradigme. Conçu pour les conteneurs et le cloud natif, il compile le maximum de travail à la phase de build plutôt qu’au démarrage. La conséquence directe pour Keycloak est un démarrage en 3 à 8 secondes contre 90 à 180 secondes avec WildFly, et une consommation mémoire au repos autour de 500 Mo à 700 Mo sur un realm simple — ce qui rend le CX31 à 8 Go tout à fait viable en production légère pour une PME de 50 à 200 utilisateurs.

La configuration passe désormais par des variables d’environnement préfixées KC_ ou par un fichier keycloak.conf en syntaxe clé=valeur, beaucoup plus lisible. La commande principale est kc.sh start (ou kc.sh start-dev en développement sans TLS). Lorsqu’on utilise l’image Docker officielle — ce que nous allons faire — toute cette mécanique est encapsulée dans l’entrypoint du conteneur : vous passez vos variables d’environnement via Docker Compose et Keycloak se configure lui-même au démarrage.

Un dernier point important : depuis Keycloak 20, la commande start --optimized suppose qu’un build a été réalisé au préalable pour pré-compiler la configuration. Pour simplifier ce tutoriel, nous utilisons start sans --optimized, ce qui exécute le build à la volée au premier démarrage — légèrement plus lent mais plus simple à maintenir pour une première installation.

Étape 2 — Déployer via Docker Compose : Postgres + Keycloak

L’architecture cible est la suivante : Traefik écoute sur les ports 80 et 443 et termine le TLS. Il transmet les requêtes vers Keycloak sur le port 8080 en HTTP interne (puisque le TLS est géré à l’extérieur). Keycloak persiste toutes ses données dans PostgreSQL. Les trois services tournent dans le même réseau Docker interne, ce qui évite d’exposer Postgres ou Keycloak directement sur l’internet.

Créez le répertoire de travail et le fichier Compose :

mkdir -p /opt/keycloak && cd /opt/keycloak
nano docker-compose.yml

Collez-y la configuration suivante. Chaque section est commentée pour expliquer le rôle de chaque variable :

version: "3.9"

services:

  postgres:
    image: postgres:16-alpine
    container_name: keycloak-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak          # Nom de la base de données
      POSTGRES_USER: keycloak        # Utilisateur Postgres dédié
      POSTGRES_PASSWORD: ${DB_PASS}  # Mot de passe lu depuis .env
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - keycloak-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    container_name: keycloak
    restart: unless-stopped
    command: start                    # Mode production (pas start-dev)
    environment:
      KC_DB: postgres                 # Adaptateur base de données
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${DB_PASS}
      KC_HOSTNAME: auth.monentreprise.com   # Nom de domaine public
      KC_PROXY: edge                  # Traefik termine le TLS (edge mode)
      KC_HTTP_ENABLED: "true"         # HTTP interne autorisé (Traefik gère HTTPS)
      KC_HTTPS_ENABLED: "false"       # Pas de TLS dans le conteneur
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: ${ADMIN_PASS}
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - keycloak-net
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.keycloak.rule=Host(`auth.monentreprise.com`)"
      - "traefik.http.routers.keycloak.entrypoints=websecure"
      - "traefik.http.routers.keycloak.tls.certresolver=letsencrypt"
      - "traefik.http.services.keycloak.loadbalancer.server.port=8080"

  traefik:
    image: traefik:v3.0
    container_name: traefik
    restart: unless-stopped
    command:
      - "--api.insecure=false"
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@monentreprise.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt
    networks:
      - keycloak-net

volumes:
  pgdata:
  letsencrypt:

networks:
  keycloak-net:
    driver: bridge

Créez maintenant le fichier .env avec des mots de passe forts générés aléatoirement. Ne réutilisez pas les exemples ci-dessous :

cat > /opt/keycloak/.env <<'EOF'
DB_PASS=Pg@2026!Xk9mQr3vLz
ADMIN_PASS=Kc@Admin!2026_Secure
EOF
chmod 600 /opt/keycloak/.env

Lancez la stack avec docker compose up -d depuis /opt/keycloak/. Les trois conteneurs démarrent dans l'ordre : Traefik d'abord (il prend immédiatement les ports 80 et 443), puis Postgres (le healthcheck garantit qu'il est prêt), puis Keycloak. Ce premier démarrage prend entre 30 et 90 secondes car Keycloak doit initialiser le schéma de base de données Postgres. Surveillez les logs avec docker compose logs -f keycloak jusqu'à voir la ligne Keycloak 26.0.X on JVM (powered by Quarkus) started.

Étape 3 — Première initialisation : realm master et compte admin

Une fois Keycloak démarré, rendez-vous sur https://auth.monentreprise.com/admin/. Vous devriez voir la page de connexion de la console d'administration. Connectez-vous avec les identifiants admin et le mot de passe ADMIN_PASS défini dans votre fichier .env.

La première chose que vous voyez est le realm master. Dans l'architecture Keycloak, un realm est un espace d'isolation complet : il a ses propres utilisateurs, ses propres clients (applications connectées), ses propres politiques de mot de passe et ses propres configurations de fédération. Le realm master est le realm de l'administrateur global de l'instance — il ne doit jamais servir à authentifier vos utilisateurs métier. Son seul rôle est de permettre à l'administrateur technique de gérer l'instance.

Avant de créer votre realm métier, renforcez la sécurité du compte admin master. Allez dans Manage → Users → admin → Credentials et cliquez sur Reset password pour définir un mot de passe robuste si ce n'est pas déjà fait. Ensuite, dans Realm settings → Login, activez Require SSL en mode All requests — Traefik garantit que toutes les requêtes arrivent déjà en HTTPS, mais cette option bloque toute connexion non-SSL au niveau Keycloak lui-même, ce qui est une bonne défense en profondeur.

Pour vérifier que la base de données est bien connectée et que les données persistent, redémarrez le conteneur Keycloak (docker compose restart keycloak) et reconnectez-vous à la console. Si votre session admin est retrouvée et que le realm master apparaît intact, la persistance Postgres fonctionne correctement.

Étape 4 — Créer le realm « monentreprise » et les clients OIDC

Dans le menu déroulant en haut à gauche de la console, cliquez sur Create Realm. Donnez-lui le nom monentreprise (tout en minuscules, sans espaces ni caractères spéciaux pour éviter les problèmes d'URL). Ce realm va concentrer tous les utilisateurs et toutes les applications de votre entreprise.

Une fois dans le realm monentreprise, la première configuration essentielle est la politique de mot de passe. Allez dans Authentication → Password Policy et ajoutez au minimum : longueur minimale 12 caractères, au moins 1 majuscule, 1 minuscule, 1 chiffre et 1 caractère spécial. En contexte PME africaine où les collaborateurs peuvent utiliser des connexions mobiles peu sécurisées, une politique de mot de passe solide est la première ligne de défense.

Créons maintenant le client OIDC pour ERPNext. Dans Clients → Create client, saisissez :

• Client ID : erpnext
• Client Protocol : openid-connect
• Access Type : confidential (ERPNext s'authentifie côté serveur)
• Valid Redirect URIs : https://erp.monentreprise.com/*
• Web Origins : https://erp.monentreprise.com

Après la sauvegarde, allez dans l'onglet Credentials du client pour copier le Client Secret — vous en aurez besoin pour configurer ERPNext côté application. Dans ERPNext, la configuration SSO se fait dans Setup → Social Login Keys en choisissant le fournisseur Custom (OAuth) et en renseignant l'URL du Discovery Document : https://auth.monentreprise.com/realms/monentreprise/.well-known/openid-configuration.

Pour Nextcloud, le processus est identique mais le type de client doit être public si vous utilisez le flux Authorization Code avec PKCE (recommandé pour les applications web), et les Redirect URIs doivent inclure https://cloud.monentreprise.com/apps/sociallogin/custom_oidc/keycloak si vous utilisez l'extension Social Login. Le Client ID et l'URL du realm suffisent pour Nextcloud en mode public — pas besoin de Client Secret.

Une fois les clients créés, créez un utilisateur test dans Users → Add user, définissez-lui un mot de passe temporaire dans l'onglet Credentials, et vérifiez le flux complet en vous rendant sur https://auth.monentreprise.com/realms/monentreprise/account/. Si la page de compte utilisateur Keycloak s'affiche après login, votre realm est opérationnel.

Étape 5 — Connecter LDAP ou Active Directory existant

Si votre entreprise dispose déjà d'un annuaire LDAP (OpenLDAP) ou d'un Active Directory Windows — situation fréquente dans les PME qui ont commencé par un réseau Windows local — Keycloak permet de fédérer ces comptes sans les migrer. Les utilisateurs continuent à utiliser leurs identifiants AD/LDAP, Keycloak les synchronise et les expose en OIDC à toutes vos applications.

Dans le realm monentreprise, allez dans User Federation → Add provider → LDAP. Les paramètres essentiels à renseigner sont les suivants :

• Vendor : choisissez Active Directory ou Other selon votre annuaire
• Connection URL : ldap://192.168.1.10:389 (adresse IP de votre contrôleur de domaine ou serveur OpenLDAP)
• Bind DN : CN=keycloak-sync,OU=ServiceAccounts,DC=monentreprise,DC=local — un compte de service dédié avec droits en lecture seule
• Bind Credential : mot de passe du compte de service
• Users DN : OU=Utilisateurs,DC=monentreprise,DC=local
• Username LDAP attribute : sAMAccountName pour AD, uid pour OpenLDAP
• RDN LDAP attribute : cn
• UUID LDAP attribute : objectGUID pour AD, entryUUID pour OpenLDAP

Cliquez sur Test connection puis Test authentication pour valider la connectivité avant de sauvegarder. Si le test échoue, vérifiez que le port 389 est accessible depuis le VPS Keycloak (règle firewall, VPN ou peering réseau). En contexte multi-sites Dakar + Abidjan, si l'AD se trouve dans l'un des bureaux, la connexion LDAP depuis le VPS Hetzner (Europe) doit passer par Internet — dans ce cas, activez impérativement le chiffrement StartTLS ou passez sur le port 636 (LDAPS) pour éviter que les identifiants transitent en clair.

Une fois la fédération configurée, cliquez sur Synchronize all users. Les comptes apparaissent dans l'onglet Users du realm. La synchronisation peut être planifiée (champ Full Sync Period en secondes) pour rester à jour quand des comptes sont créés ou supprimés dans l'AD.

Étape 6 — MFA par défaut : WebAuthn + TOTP

Keycloak supporte deux mécanismes de MFA principaux : le TOTP (Time-based One-Time Password, compatible Google Authenticator, FreeOTP, Aegis) et le WebAuthn (clés de sécurité physiques FIDO2 comme YubiKey, ou authentificateurs biométriques intégrés aux téléphones). En 2026, WebAuthn est la méthode recommandée car elle résiste au phishing — la clé est liée à l'origine exacte du site et ne peut pas être réutilisée sur un faux site.

Pour activer le TOTP comme exigence par défaut dans votre realm, allez dans Authentication → Flows. Sélectionnez le flow browser, cliquez sur Duplicate pour créer une copie modifiable, et renommez-la browser-mfa. Dans ce flow copié, ajoutez une étape OTP Form en mode Required après l'étape de formulaire de mot de passe. Revenez dans Authentication → Required Actions et activez par défaut Configure OTP — ainsi, chaque nouvel utilisateur sera invité à configurer son TOTP lors de sa première connexion.

Pour WebAuthn, allez dans Authentication → WebAuthn Policy. Les réglages recommandés pour une PME sont :

• Relying Party Name : monentreprise.com
• Signature Algorithms : ES256 (ECDSA avec SHA-256 — supporté par la quasi-totalité des authentificateurs)
• Attestation Conveyance : None (plus simple, suffisant pour la plupart des cas)
• Authenticator Attachment : Not specified (accepte clés physiques ET authentificateurs de plateforme comme Face ID/empreinte)
• User Verification Requirement : Required (force la vérification biométrique ou PIN sur l'authentificateur)

Dans le flow browser-mfa, ajoutez également une étape WebAuthn Authenticator en mode Alternative par rapport au TOTP — l'utilisateur pourra ainsi choisir entre les deux méthodes à chaque connexion. Définissez ce flow personnalisé comme flow browser actif dans Realm settings → Authentication flows → Browser flow.

Étape 7 — Reverse proxy Traefik avec X-Forwarded-Proto

La configuration Traefik déjà présente dans notre Docker Compose gère l'essentiel, mais il faut comprendre pourquoi la variable KC_PROXY=edge est critique. Sans elle, Keycloak reçoit les requêtes de Traefik en HTTP interne et croit fonctionner sans TLS. Il génère alors des URLs de redirection en http:// au lieu de https://, ce qui casse les flux OAuth2/OIDC et produit des erreurs redirect_uri_mismatch difficiles à diagnostiquer.

Avec KC_PROXY=edge, Keycloak fait confiance aux en-têtes X-Forwarded-Proto, X-Forwarded-Host et X-Forwarded-For transmis par Traefik, et génère correctement toutes ses URLs en https://. Traefik transmet automatiquement ces en-têtes sans configuration supplémentaire.

Pour vérifier que la chaîne fonctionne correctement de bout en bout, appelez le Discovery Document depuis l'extérieur :

curl -s https://auth.monentreprise.com/realms/monentreprise/.well-known/openid-configuration \
  | python3 -m json.tool | grep issuer

La valeur retournée doit être "issuer": "https://auth.monentreprise.com/realms/monentreprise" — en HTTPS, avec votre domaine exact. Si vous voyez http:// ou une adresse IP, KC_PROXY=edge n'est pas correctement pris en compte ou KC_HOSTNAME n'est pas défini. Si vous obtenez une erreur TLS, vérifiez que Let's Encrypt a bien émis le certificat pour votre domaine (docker compose logs traefik | grep acme).

Erreurs fréquentes

Adaptation au contexte ouest-africain

Déployer Keycloak en Afrique de l'Ouest soulève plusieurs contraintes spécifiques que ce tutoriel serait incomplet de passer sous silence. La première est la consommation mémoire : Keycloak est une application Java, et Java consomme de la RAM même quand il ne fait rien. Sur un CX21 (4 Go), vous serez en tension permanente dès que vous avez plus d'un realm actif, des sessions LDAP ouvertes et quelques authentifications simultanées. Le CX31 à 8 Go est le minimum absolu pour la production, et si votre entreprise dépasse 150 utilisateurs actifs simultanément, envisagez le CX41 (16 Go). Hetzner facture à l'heure : vous pouvez redimensionner en 2 minutes si le besoin se fait sentir.

La deuxième adaptation concerne les sauvegardes de la base Postgres. Dans un contexte où l'accès à un DBA ou à une équipe infrastructure est rare, la stratégie la plus simple et la plus fiable est une sauvegarde quotidienne automatisée vers Backblaze B2 — moins cher que S3, avec un datacenter accessible depuis l'Afrique et une API S3-compatible. Installez rclone sur le serveur Hetzner, configurez un remote Backblaze, et planifiez ce script dans cron :

# /etc/cron.d/keycloak-backup
0 2 * * * root docker exec keycloak-db pg_dump -U keycloak keycloak \
  | gzip | rclone rcat backblaze:mon-bucket/keycloak/$(date +\%F).sql.gz

Cette ligne sauvegarde la base à 2h du matin chaque nuit, compresse le dump et l'envoie directement vers Backblaze sans écrire sur le disque local. Testez la restauration au moins une fois par mois avec rclone copy suivi d'un pg_restore sur une base de test.

La troisième adaptation concerne la fédération multi-sites. Pour une PME avec des bureaux à Dakar et à Abidjan, Keycloak est idéalement déployé sur un seul VPS accessible depuis les deux sites via Internet. La latence LDAP entre Hetzner (Frankfurt ou Helsinki) et un AD dans un bureau dakarois peut atteindre 80 à 120 ms sur une bonne connexion FTTH, et 200 à 400 ms sur une connexion mobile 4G. Pour minimiser l'impact, activez la synchronisation périodique plutôt que la synchronisation à chaque connexion : Keycloak met en cache les données LDAP localement dans Postgres pendant la durée de vie du cache (paramètre Cache Policy du provider LDAP). Ainsi, même si la liaison vers l'AD est momentanément interrompue, les utilisateurs peuvent continuer à se connecter via le cache.

Enfin, si votre serveur Hetzner est à Helsinki ou Frankfurt, la latence perçue depuis Abidjan ou Dakar sera de 60 à 100 ms — tout à fait acceptable pour une interface web d'authentification où les requêtes sont ponctuelles. Keycloak ne génère pas de flux de données continus : une authentification SSO ne coûte qu'une ou deux requêtes HTTP, même avec MFA.

Tutoriels frères

• Authelia avec Traefik : SSO léger pour homelab et petite équipe (2026) — si Keycloak est trop lourd pour votre infrastructure, Authelia offre le SSO avec 50 Mo de RAM
• Authentik : installation Docker et premier provider OIDC (2026) — alternative moderne à Keycloak avec une UI plus intuitive et une gestion fine des flux d'enrôlement
• Connecter ERPNext à Keycloak via OIDC : guide pas-à-pas — configuration côté ERPNext en détail, gestion des rôles et mappage d'attributs

Pour aller plus loin

• Retour au pilier : IAM open-source pour PME : Keycloak, Authelia, Authentik comparés (2026)
• Documentation officielle Keycloak : keycloak.org/documentation — guide d'administration du serveur, guide de configuration, guides des opérations
• Code source et issues GitHub : github.com/keycloak/keycloak — pour suivre les releases, signaler des bugs et consulter les changelogs détaillés
• Image Docker officielle : quay.io/repository/keycloak/keycloak
• Prochaine étape suggérée : une fois Keycloak opérationnel, configurez les Client Scopes pour contrôler finement quels attributs utilisateur sont transmis à chaque application OIDC — voir la section Client Scopes de la documentation officielle

FAQ