Pourquoi déployer Keycloak sur votre VPS
Là où certains IdP visent la simplicité, Keycloak vise l'exhaustivité : isolation multi-tenant via les realms, fédération d'annuaires LDAP/Active Directory, brokering vers des fournisseurs externes (Google, GitHub, un autre OIDC), théming complet des pages de login et fine-grained authorization. Pour une agence qui gère plusieurs clients ou un SI avec des exigences de conformité, ce niveau de contrôle est décisif. Le self-hébergement sur VPS vous évite les coûts par utilisateur des offres IdP managées et garde l'intégralité de la base d'identités sous votre juridiction, un point critique pour des données sensibles que vous ne souhaitez pas confier à un tiers.
Les atouts d'un Keycloak auto-hébergé
- Réalms multiples pour isoler totalement plusieurs clients ou environnements sur une même instance.
- Support natif et complet d'OpenID Connect, OAuth2 et SAML 2.0.
- Fédération LDAP / Active Directory pour réutiliser un annuaire existant sans migration.
- Identity brokering : connexion via Google, GitHub ou tout IdP externe en quelques clics.
- Pages de login entièrement personnalisables (thèmes, langues, branding par realm).
- Politiques d'authentification fines : MFA conditionnel, durée de session, contraintes par rôle.
Prérequis pour ce déploiement
Keycloak tourne sur la JVM (Quarkus depuis la v17+) et reste plus gourmand qu'un IdP léger. Prévoyez un VPS avec 2 vCPU et 4 Go de RAM au minimum, idéalement 6 Go si vous attendez de la charge ou plusieurs realms actifs. Une base PostgreSQL externe est fortement recommandée en production (n'utilisez jamais la base H2 embarquée au-delà des tests). Docker et Docker Compose, un domaine dédié (sso.mondomaine.com) et un reverse proxy gérant le SSL complètent les prérequis, car Keycloak attend d'être informé qu'il est servi derrière un proxy HTTPS.
Déployer Keycloak avec PostgreSQL
Définir Keycloak et PostgreSQL dans Compose
Dans votre
docker-compose.yml, déclarez le servicepostgres(imagepostgres:16) et le servicekeycloak(imagequay.io/keycloak/keycloak). Reliez Keycloak à la base viaKC_DB=postgres,KC_DB_URL,KC_DB_USERNAMEetKC_DB_PASSWORD.Configurer le mode production et le proxy
Lancez avec la commande
start(et nonstart-dev). RenseignezKC_HOSTNAME=sso.mondomaine.cometKC_PROXY_HEADERS=xforwardedpour que Keycloak génère des URL correctes derrière le reverse proxy. Définissez l'admin initial viaKC_BOOTSTRAP_ADMIN_USERNAME/KC_BOOTSTRAP_ADMIN_PASSWORD.Démarrer et terminer le build
Exécutez
docker compose up -d. Au premier démarrage, Keycloak réalise un build Quarkus optimisé puis migre le schéma PostgreSQL. Suivezdocker compose logs -f keycloakjusqu'au message indiquant que le serveur écoute.Mettre en place le reverse proxy SSL
Routez
sso.mondomaine.comvers le port8080du conteneur Keycloak via Caddy, Traefik ou Nginx, avec un certificat Let's Encrypt. Veillez à transmettre les en-têtesX-Forwarded-*faute de quoi les redirections de login casseront.Créer un realm et un client
Connectez-vous à la console d'admin, créez un realm dédié (jamais le realm
masterpour vos apps), puis un client OIDC. Réglez leValid redirect URIsde votre application et récupérez leClient IDet le secret dans l'onglet Credentials.Brancher une application et tester le flow
Configurez votre app avec l'URL de découverte
https://sso.mondomaine.com/realms/mon-realm/.well-known/openid-configuration. Créez un utilisateur de test dans le realm, lancez un login et vérifiez l'émission du token dans les Sessions de la console.
Image préoptimisée : séparer le build du démarrage
Par défaut, la commande start vérifie au démarrage si une phase de build Quarkus est nécessaire et la déroule au besoin : c'est ce qui allonge le premier démarrage, et c'est ce qui écrit dans l'arborescence de l'installation. La documentation de l'éditeur recommande l'inverse pour un conteneur : exécuter kc.sh build pendant la construction de l'image, puis démarrer avec start --optimized. Le paramètre --optimized indique à Keycloak qu'il tourne dans une image déjà optimisée et qu'il peut sauter cette vérification. Les options de build, comme le type de base de données (db) ou l'activation des sondes (health-enabled), sont figées dans l'image : repassées au démarrage avec la même valeur, elles sont ignorées ; avec une valeur différente, elles provoquent une erreur et exigent un nouveau build. Les secrets, mot de passe de la base compris, relèvent des options de configuration et restent fournis à l'exécution.
Construire et lancer une image préoptimisée
Écrire un Dockerfile en deux étapes
La première étape part de
quay.io/keycloak/keycloaknomméebuilder, poseENV KC_DB=postgresetENV KC_HEALTH_ENABLED=true, puis exécuteRUN /opt/keycloak/bin/kc.sh build. Épinglez un numéro de version précis plutôt quelatest, afin que chaque reconstruction reste reproductible.Copier le résultat dans l'image finale
La seconde étape repart de la même image et exécute
COPY --from=builder /opt/keycloak/ /opt/keycloak/. Déposez vos thèmes et fournisseurs personnalisés avant le build : ils sont alors pris en compte par l'optimisation. Si vous ajoutez des fichiers avecCOPY, ajoutez--chown=keycloak:keycloakpour que Keycloak puisse écrire dans les dossiers concernés.Démarrer avec l'option optimisée
Dans Compose, remplacez la commande par
start --optimized. Derrière un reverse proxy qui termine le TLS, ajoutezKC_HTTP_ENABLED=true. Les variablesKC_HOSTNAME,KC_PROXY_HEADERSet les accès à la base restent de la configuration d'exécution.Brancher les sondes de santé
Avec
KC_HEALTH_ENABLED=trueposé au build, les points/health/started,/health/liveet/health/readysont servis sur le port de gestion9000, distinct du8080applicatif. Ne publiez pas ce port sur Internet : utilisez-le seulement pour lehealthcheckde Compose ou votre supervision.
Keycloak ou Authentik : que choisir ?
Faites défiler le tableau
| Critère | Keycloak | Authentik |
|---|---|---|
| Cas d'usage cible | SSO d'entreprise, multi-tenant, conformité | Self-hosting, homelab, agences |
| Protocoles | OIDC, OAuth2, SAML, LDAP | OIDC, OAuth2, SAML, LDAP, forward auth |
| Forward auth (proxy) | Non natif (via extensions) | Natif et central à l'outil |
| Empreinte ressources | Élevée (JVM, 4 Go+ RAM) | Modérée (2-4 Go RAM) |
| Multi-realm / tenants | Excellent (realms isolés) | Tenants supportés, moins poussés |
| Personnalisation des flows | Thèmes et SPI Java | Flows visuels par étapes |
| Courbe d'apprentissage | Raide, très complet | Plus accessible |
| Fédération d'annuaires | Mature (LDAP/AD) | Bonne (LDAP) |
Sauvegarder et migrer sans perdre un realm
L'état de Keycloak tient en deux endroits : la base PostgreSQL, et vos fichiers de configuration (thèmes, fournisseurs, fichiers d'import). La sauvegarde de référence est un pg_dump planifié, copié hors du VPS ; testez la restauration sur une instance jetable, car une sauvegarde jamais restaurée reste une hypothèse. L'export de realm complète ce dispositif sans le remplacer : kc.sh export --dir <dossier>, ou --realm mon-realm pour un seul realm, avec l'option --users pour choisir la stratégie d'export des utilisateurs. La documentation précise que le serveur ne doit pas être démarré pendant l'export, que la cohérence n'est garantie qu'avec tous les nœuds arrêtés, et que les événements, les sessions persistées et les jetons révoqués ne sont pas exportés. Au-delà de 50 000 utilisateurs, exportez vers un répertoire plutôt que vers un fichier unique. À l'import, start --import-realm lit les fichiers .json du dossier /opt/keycloak/data/import et ignore un realm qui existe déjà.
Checklist d'exploitation
- Version épinglée — fixez le numéro de version de l'image, lisez les notes de version avant de changer de branche majeure et reconstruisez l'image optimisée à chaque montée de version.
- Base sauvegardée —
pg_dumpplanifié, copie hors du VPS, restauration éprouvée sur une instance jetable. - Mémoire bornée — fixez toujours une limite de mémoire au conteneur : la JVM calcule son tas à partir d'elle, avec par défaut 70 % au maximum et 50 % au départ.
- Sondes surveillées — suivez
/health/readysur le port9000, non publié, depuis votre supervision. - En-têtes de proxy maîtrisés — le reverse proxy doit écraser les en-têtes
X-Forwarded-*reçus du client, pas s'y ajouter, et ne jamais être contourné. - Événements activés — journalisez les connexions et les actions d'administration dans chaque realm, pour savoir qui s'est connecté et qui a modifié quoi.
Dépannage : démarrage en échec avec un système de fichiers en lecture seule
Durcir un conteneur passe souvent par read_only: true dans Compose ou readOnlyRootFilesystem: true dans Kubernetes. Avec Keycloak, le sujet est ouvert depuis avril 2022 dans l'issue keycloak/keycloak n° 11286 (« Keycloak does not work with Docker read_only: true »), et elle était encore active fin octobre 2026. Ce qui est établi côté projet : un contributeur de Keycloak a reproduit l'échec sur la version 19.0.2 en septembre 2022, l'issue est classée en amélioration avec l'étiquette « help wanted », et elle a été ajoutée à un tableau de projet du dépôt en septembre 2026. Ce qui ne l'est pas : la documentation officielle ne décrit à ce jour aucun mode lecture seule (la page consacrée aux conteneurs n'en parle pas), et aucun mainteneur n'a validé de contournement. Les solutions ci-dessous viennent de participants à la discussion ; elles ont fonctionné chez eux, sur leurs versions, sans garantie après une montée de version. Le 26 octobre 2026, un contributeur a proposé d'écrire la documentation manquante après avoir vérifié lui-même ces contournements.
Les messages d'erreur à reconnaître
sed: couldn't open temporary file /opt/jboss/keycloak/bin/seduHoQM0: Read-only file system— message du rapport initial, sur l'ancienne image WildFly (version 16.1.1 dans l'issue) : unsed -idu script de démarrage ne peut pas créer son fichier temporaire. Sur la distribution Quarkus, les symptômes sont différents, voir les lignes suivantes.KC-SERVICES0075: Failed to get theme request: java.lang.RuntimeException: Temporary directory /opt/keycloak/bin/../data/tmp does not exist and it was not possible to create it.— rapporté lors d'une montée vers la 20.0.1 : le serveur démarre, puis échoue sur la première page qui sert un thème. Un participant a signalé qu'un volume inscriptible monté sur/opt/keycloak/data/tmprègle ce cas.- Démarrage lent ou échec d'écriture dans
/opt/keycloak/lib/quarkus— un participant a comparé le conteneur avant et après démarrage avecdocker diff: trois dossiers changent,/tmp,/opt/keycloak/dataet/opt/keycloak/lib/quarkus. Le dernier contient le produit du build, questartrégénère sauf si l'image est préoptimisée. - Dossier
dataen lecture seule après unCOPY— un participant signale qu'oublier--chown=keycloak:keycloaksur la copie d'un fichier de realm laisse/opt/keycloak/datadétenu par root, donc non inscriptible par Keycloak. - Copie de
/opt/keycloakdans un volume au démarrage — contournement par conteneur d'initialisation, rapporté sous Kubernetes : il fonctionne, mais plusieurs participants redoutent de devoir le retester à chaque montée de version.
Contournement rapporté dans Docker Compose
Partir de l'image préoptimisée
Reprenez l'image construite plus haut. Le
kc.sh builds'exécute à la construction :/opt/keycloak/lib/quarkusn'est plus réécrit au démarrage, qui se fait avecstart --optimized.Déclarer le système de fichiers en lecture seule
Ajoutez
read_only: trueau servicekeycloakdu fichier Compose. Sans autre changement, le conteneur échoue : c'est le comportement décrit par l'issue.Fournir les répertoires inscriptibles
Montez un
tmpfssur/tmpet un volume temporaire sur/opt/keycloak/data. Dans le retour qui s'appuie sur une image préoptimisée, ces deux répertoires ont suffi ; sur une image non optimisée, d'autres participants ont ajouté/opt/keycloak/lib/quarkus.Replacer ce qui se trouvait dans data
Un volume temporaire démarre vide : ce que l'image plaçait dans ce dossier, dont
data/import, n'y est plus visible. Si vous importez des realms avec--import-realm, montez leur dossier séparément, en lecture seule.Vérifier en ouvrant une page de login
Lancez
docker compose up -dpuisdocker compose logs -f keycloak, ouvrez ensuite la page de connexion : c'est la première requête de thème qui a fait échouer certains montages. Terminez pardocker diffpour lister ce que le conteneur a réellement écrit.
Lecture seule : un durcissement que l'éditeur ne documente pas
Gardez ce mode pour les environnements où une politique l'exige, comme un audit de sécurité ou une règle de cluster, et acceptez le coût : une configuration non documentée, à retester à chaque montée de version, ce que plusieurs participants de l'issue redoutent. Sur un VPS unique, d'autres mesures donnent un gain plus net pour moins d'entretien : capacités Linux retirées (cap_drop: [ALL]), option no-new-privileges, ports de gestion non publiés et base PostgreSQL sur un réseau Docker interne.
En production, ne servez jamais Keycloak avec la base H2 embarquée et n'exposez pas le realm master au public : créez un realm dédié par application ou par client, et réservez master à l'administration. Pour durcir l'instance, désactivez l'enregistrement libre, activez le brute force detection dans Realm Settings > Security Defenses, et provisionnez tout via des fichiers d'import realm (--import-realm) afin de versionner votre configuration plutôt que de cliquer dans l'UI.
