En tant que formatrice BTS SIO et développeuse web, je constate que la question de l’authentification revient systématiquement dans les projets professionnels. Gérer soi-même les mots de passe, les sessions et les tokens JWT représente un risque de sécurité considérable. C’est exactement pour cela que je recommande Keycloak, une solution open source de gestion des identités et des accès (IAM), et que je vous propose de le déployer avec Docker pour simplifier toute la chaîne d’installation.

Dans ce guide, je vous accompagne pas à pas : du simple conteneur de test jusqu’à une configuration prête pour la production avec Docker Compose, PostgreSQL et HTTPS. Que vous soyez étudiant en alternance informatique ou développeur confirmé, vous aurez un serveur d’authentification fonctionnel en quelques minutes.

Comprendre Keycloak et son rôle dans la gestion des identités

Keycloak est un serveur d’identité et d’accès développé à l’origine par Red Hat. Il implémente les protocoles OpenID Connect, OAuth 2.0 et SAML 2.0, ce qui en fait une brique centrale pour sécuriser vos applications web, vos API REST et vos microservices. Concrètement, au lieu de coder l’authentification dans chaque application, vous déléguez cette responsabilité à Keycloak, qui gère pour vous les connexions, les inscriptions, la fédération d’identités (Google, GitHub, LDAP) et le contrôle d’accès par rôles.

Pourquoi l’associer à Docker ? Parce que Keycloak nécessite un serveur d’application Java (Quarkus depuis la version 17) et une base de données relationnelle. Sans conteneurisation, l’installation implique de configurer manuellement le JDK, le serveur et la base. Avec Docker, une seule commande suffit pour obtenir un environnement complet et reproductible. C’est un gain de temps considérable, surtout quand on travaille en équipe ou que l’on souhaite automatiser ses déploiements avec un pipeline CI/CD.

Selon la documentation officielle de Keycloak, le projet compte plus de 18 000 étoiles sur GitHub et il est utilisé par des entreprises de toutes tailles pour centraliser leur gestion des accès.

Prérequis avant l’installation de Keycloak avec Docker

Avant de lancer votre premier conteneur Keycloak, vérifiez que votre poste de travail remplit les conditions suivantes :

• Docker Engine 20.10+ ou Docker Desktop installé et fonctionnel. Tapez docker --version dans votre terminal pour vérifier.
• Docker Compose v2 (intégré à Docker Desktop, ou installable séparément sur Linux). Vérifiez avec docker compose version.
• Au minimum 2 Go de RAM disponibles pour le conteneur Keycloak (4 Go recommandés en production).
• Un port réseau libre : par défaut, Keycloak écoute sur le port 8080 (HTTP) et 8443 (HTTPS).
• Un éditeur de texte pour créer vos fichiers de configuration (VS Code, nano, vim).

Si vous hésitez entre Docker et d’autres solutions de conteneurisation, je vous invite à lire mon comparatif Podman vs Docker qui détaille les avantages de chaque outil. Pour ce tutoriel, je me base sur Docker car c’est le standard le plus répandu dans les environnements de développement.

Un point important : depuis la version 20, l’équipe Keycloak a migré l’image officielle de Docker Hub vers le registre quay.io. L’image à utiliser est désormais quay.io/keycloak/keycloak. L’ancienne image jboss/keycloak est obsolète et ne reçoit plus de mises à jour de sécurité.

Lancer Keycloak avec Docker en une seule commande

Pour tester Keycloak rapidement en local, une seule commande suffit. Ouvrez votre terminal et tapez :

docker run -d --name keycloak-dev \
  -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:25.0 \
  start-dev

Décortiquons cette commande :

• -d : lance le conteneur en arrière-plan (mode détaché).
• --name keycloak-dev : donne un nom lisible au conteneur.
• -p 8080:8080 : expose le port 8080 du conteneur sur votre machine.
• -e KC_BOOTSTRAP_ADMIN_USERNAME et KC_BOOTSTRAP_ADMIN_PASSWORD : définissent les identifiants de l’administrateur initial.
• start-dev : lance Keycloak en mode développement, avec une base H2 embarquée et le rechargement à chaud activé.

Après quelques secondes (le démarrage prend entre 15 et 45 secondes selon votre machine), accédez à http://localhost:8080 dans votre navigateur. Vous verrez la page d’accueil de Keycloak. Cliquez sur Administration Console et connectez-vous avec les identifiants définis ci-dessus.

Pour vérifier que le conteneur fonctionne correctement, utilisez :

docker logs keycloak-dev

Vous devriez voir la ligne Keycloak 25.0 on JVM (powered by Quarkus) started. Si le conteneur s’arrête immédiatement, les logs vous indiqueront la cause exacte de l’erreur.

Déployer Keycloak avec Docker Compose et PostgreSQL

Le mode développement utilise une base H2 embarquée qui perd toutes les données à chaque redémarrage du conteneur. Pour un environnement stable, je recommande d’utiliser Docker Compose avec PostgreSQL. Si vous n’êtes pas encore à l’aise avec la syntaxe, consultez mon guide pratique Docker Compose YML.

Créez un fichier docker-compose.yml à la racine de votre projet :

version: '3.9'

services:
  postgres:
    image: postgres:16-alpine
    container_name: keycloak-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: motdepasse_securise
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - keycloak-net

  keycloak:
    image: quay.io/keycloak/keycloak:25.0
    container_name: keycloak-app
    restart: unless-stopped
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: motdepasse_securise
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: ChangezCeMotDePasse2026!
      KC_HOSTNAME: localhost
    ports:
      - "8080:8080"
    depends_on:
      - postgres
    networks:
      - keycloak-net
    command: start-dev

volumes:
  postgres_data:

networks:
  keycloak-net:
    driver: bridge

Lancez l’ensemble avec :

docker compose up -d

Docker va télécharger les images si nécessaire, créer le réseau, démarrer PostgreSQL puis Keycloak. Les données sont désormais persistées dans un volume Docker nommé postgres_data. Même si vous arrêtez et relancez les conteneurs, vos realms, utilisateurs et configurations seront conservés.

Pour suivre les logs des deux services en temps réel :

docker compose logs -f

Configurer Keycloak : premier realm et premier utilisateur

Une fois connecté à la console d’administration, vous êtes dans le realm master. Ce realm est réservé à l’administration de Keycloak lui-même. Pour vos applications, créez toujours un realm dédié.

Créer un nouveau realm

1. Dans le menu déroulant en haut à gauche (qui affiche « master »), cliquez sur Create Realm.
2. Donnez-lui un nom explicite, par exemple mon-application.
3. Cliquez sur Create.

Créer un client (application)

1. Dans votre nouveau realm, allez dans Clients puis Create client.
2. Choisissez le type OpenID Connect.
3. Renseignez un Client ID (par exemple mon-app-web).
4. Activez Client authentication si votre application est une API backend.
5. Configurez les Valid redirect URIs : http://localhost:3000/* pour un front en développement.

Créer un utilisateur de test

1. Allez dans Users puis Add user.
2. Renseignez le nom d’utilisateur, l’email et cochez Email verified.
3. Dans l’onglet Credentials, définissez un mot de passe temporaire.

Vous pouvez aussi importer des configurations existantes au démarrage du conteneur en montant un volume contenant vos fichiers JSON d’export. C’est particulièrement utile pour automatiser le provisionnement dans un pipeline CI/CD :

docker run -d --name keycloak-import \
  -v ./realm-export.json:/opt/keycloak/data/import/realm-export.json \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:25.0 \
  start-dev --import-realm

Préparer Keycloak Docker pour la production

Le mode start-dev est strictement réservé au développement. Pour un déploiement en production, plusieurs ajustements sont indispensables. Voici les points critiques que je vérifie systématiquement avec mes étudiants en alternance informatique :

Activer HTTPS

Keycloak gère des tokens d’authentification sensibles. Le HTTPS n’est pas optionnel. Vous pouvez soit configurer un reverse proxy (Nginx, Traefik, Caddy) devant Keycloak, soit fournir directement un certificat TLS au conteneur :

KC_HOSTNAME: auth.mondomaine.fr
KC_PROXY_HEADERS: xforwarded
KC_HTTP_ENABLED: "false"
KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/conf/cert.pem
KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/conf/key.pem

Je recommande personnellement l’approche reverse proxy avec Let’s Encrypt, car elle centralise la gestion des certificats. La documentation officielle Keycloak sur les reverse proxies détaille les en-têtes à configurer.

Utiliser le mode optimisé

En production, remplacez start-dev par un build optimisé. Cela pré-compile les thèmes, optimise les caches et désactive le rechargement à chaud :

FROM quay.io/keycloak/keycloak:25.0 AS builder

ENV KC_DB=postgres
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:25.0

COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]
CMD ["start", "--optimized"]

Ce Dockerfile multi-stage produit une image plus légère et plus rapide au démarrage. Le temps de boot passe typiquement de 30 secondes à moins de 10 secondes.

Sécuriser les mots de passe

Ne stockez jamais les mots de passe en clair dans le docker-compose.yml. Utilisez les secrets Docker ou des fichiers .env exclus du contrôle de version :

# fichier .env (ajoutez-le dans .gitignore)
KC_DB_PASSWORD=V0tr3_M0t_D3_P4ss3_Pr0d
KC_BOOTSTRAP_ADMIN_PASSWORD=Adm1n_S3cur1s3_2026!

Un firewall correctement configuré complète la sécurisation en limitant l’accès réseau aux seuls ports nécessaires.

Diagnostiquer les erreurs courantes de Keycloak sous Docker

Au fil de mes formations, j’ai identifié les erreurs qui reviennent le plus souvent lorsque l’on débute avec Keycloak Docker. Voici comment les résoudre :

Le conteneur s’arrête immédiatement

Consultez les logs avec docker logs keycloak-dev. Les causes les plus fréquentes sont :

• Port déjà utilisé : changez le mapping de port dans votre commande (-p 8081:8080).
• Mémoire insuffisante : augmentez la RAM allouée à Docker (dans Docker Desktop, section Resources).
• Base de données inaccessible : vérifiez que le conteneur PostgreSQL est bien démarré et que les identifiants correspondent.

Erreur de connexion à la base de données

Si vous voyez Connection refused dans les logs, vérifiez que :

• Les deux conteneurs sont sur le même réseau Docker.
• Le nom d’hôte dans KC_DB_URL correspond exactement au nom du service dans le docker-compose.yml.
• PostgreSQL a fini son initialisation avant que Keycloak ne tente de se connecter (utilisez depends_on avec un health check).

La console d’administration est inaccessible

En production, si vous accédez à Keycloak via un nom de domaine, vérifiez que KC_HOSTNAME correspond exactement à l’URL utilisée. Une erreur de configuration du hostname est la cause numéro un des problèmes d’accès à la console.

Analyser les logs en détail

Pour augmenter le niveau de verbosité des logs Keycloak :

docker run -d --name keycloak-debug \
  -e KC_LOG_LEVEL=DEBUG \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:25.0 \
  start-dev

Le mode DEBUG génère beaucoup de sortie, mais il est précieux pour identifier les problèmes de connexion, de certificat ou de configuration de realm.

Comparatif des modes de déploiement Keycloak

Pour vous aider à choisir la bonne approche selon votre contexte, voici un tableau comparatif des différentes méthodes de déploiement :

Pour les projets d’entreprise nécessitant de la haute disponibilité, Docker Swarm ou Kubernetes permettent de déployer plusieurs instances Keycloak derrière un load balancer. La configuration du cache distribué (Infinispan) demande cependant une expertise supplémentaire.

Aller plus loin avec Keycloak Docker

Une fois votre instance Keycloak fonctionnelle, plusieurs pistes s’offrent à vous pour enrichir votre déploiement :

Personnaliser les thèmes

Keycloak permet de personnaliser entièrement les pages de connexion, d’inscription et de réinitialisation de mot de passe. Montez un volume contenant votre thème personnalisé :

volumes:
  - ./mon-theme:/opt/keycloak/themes/mon-theme

Activer les métriques Prometheus

En ajoutant KC_METRICS_ENABLED=true et KC_HEALTH_ENABLED=true, vous exposez des endpoints /metrics et /health compatibles avec Prometheus et Grafana. C’est indispensable pour superviser votre instance en production.

Fédérer des sources d’identité

Keycloak peut se connecter à un annuaire LDAP ou Active Directory, ou proposer la connexion via des fournisseurs sociaux (Google, GitHub, Facebook). Tout se configure depuis la console d’administration, sans toucher au conteneur Docker.

Sauvegarder et restaurer

Exportez régulièrement vos realms pour disposer d’une sauvegarde :

docker exec keycloak-app /opt/keycloak/bin/kc.sh export \
  --dir /opt/keycloak/data/export \
  --realm mon-application

Pensez aussi à sauvegarder le volume PostgreSQL avec pg_dump pour une restauration complète en cas de sinistre.

Si vous développez des applications web qui se connecteront à Keycloak, maîtriser les bases du HTML, CSS et JavaScript est un prérequis pour intégrer correctement les formulaires de connexion et les redirections OAuth. Pour les applications backend en PHP, la documentation PHP vous aidera à intégrer les bibliothèques client OpenID Connect.

Lucie Moreau

Formatrice IT indépendante depuis 2016, ancienne étudiante BTS SIO SLAM. 6 ans d'expérience en entreprise.