Installer Keycloak avec Docker

Ce guide vous permet d’installer Keycloak avec Docker pour le développement et la formation. Vous apprendrez à démarrer Keycloak rapidement, configurer Docker Compose avec PostgreSQL, et accéder à la console d’administration.

Autres méthodes d'installation

Ce guide couvre l’installation Docker / Docker Compose, idéale pour la formation et le développement.

Les autres méthodes d’installation seront documentées séparément :

• VM Linux avec systemd — pour la production classique
• Kubernetes Operator / Helm — pour la production haute disponibilité

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Démarrer Keycloak en mode dev pour tester rapidement
• Configurer Docker Compose avec PostgreSQL pour la persistance
• Accéder à la console d’administration et créer un compte admin
• Identifier les variables essentielles de configuration

Prérequis

• Docker installé (guide d’installation)
• Docker Compose (inclus dans Docker Desktop, ou docker-compose-plugin sur Linux)

Rappel théorique

Avant d’installer Keycloak, assurez-vous de comprendre les concepts fondamentaux. Le module Présentation Keycloak explique ce qu’est un Identity Provider, les realms, clients et rôles.

Les deux modes d’exécution

Keycloak propose deux modes d’exécution :

Aspect	Mode développement (start-dev)	Mode production (start)
Base de données	H2 embarqué (données en mémoire)	PostgreSQL, MySQL, MariaDB
TLS/HTTPS	Désactivé	Obligatoire
Hostname	localhost par défaut	Doit être configuré
Cache	Local uniquement	Distribué (Infinispan)
Usage	Tests, labs, formation	Production, staging

Glissez pour voir

Ne jamais utiliser start-dev en production

Le mode start-dev désactive les contrôles de sécurité. Les logs affichent clairement :

WARN  Running the server in development mode. DO NOT use this configuration in production.

Démarrage rapide (sans persistance)

La méthode la plus rapide pour tester Keycloak :

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

Ce que fait cette commande :

• Télécharge l’image Keycloak 26.x depuis Quay.io
• Lance Keycloak sur le port 8080
• Crée un compte admin admin/admin
• Démarre en mode développement (base H2 en mémoire)

Vérification : Ouvrez http://localhost:8080

Données non persistées

Avec cette méthode, les données sont perdues à chaque redémarrage du conteneur. Pour la formation, utilisez Docker Compose avec PostgreSQL (section suivante).

Docker Compose avec PostgreSQL (recommandé)

Pour un environnement de formation avec persistance des données :

1. Créer le répertoire de travail

   mkdir -p ~/Projets/keycloak && cd ~/Projets/keycloak

2. Créer le fichier docker-compose.yml

   docker-compose.yml

   services:
     postgres:
       image: postgres:16-alpine
       container_name: keycloak-db
       environment:
         POSTGRES_DB: keycloak
         POSTGRES_USER: keycloak
         POSTGRES_PASSWORD: keycloak
       volumes:
         - postgres_data:/var/lib/postgresql/data
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U keycloak"]
         interval: 5s
         timeout: 5s
         retries: 5
       networks:
         - keycloak-net
   
     keycloak:
       image: quay.io/keycloak/keycloak:26
       container_name: keycloak
       command: start-dev
       environment:
         KC_DB: postgres
         KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
         KC_DB_USERNAME: keycloak
         KC_DB_PASSWORD: keycloak
         KC_HOSTNAME: localhost
         KC_BOOTSTRAP_ADMIN_USERNAME: admin
         KC_BOOTSTRAP_ADMIN_PASSWORD: admin
       ports:
         - "8080:8080"
       depends_on:
         postgres:
           condition: service_healthy
       networks:
         - keycloak-net
   
   volumes:
     postgres_data:
   
   networks:
     keycloak-net:
       driver: bridge

3. Démarrer les services

   docker compose up -d

4. Suivre les logs

   docker compose logs -f keycloak

   Attendez de voir :

   Keycloak 26.x.x on JVM (powered by Quarkus) started in X.XXXs. Listening on: http://0.0.0.0:8080

5. Ouvrir la console

   Accédez à http://localhost:8080

Pinning de version

Utilisez :26 (major pin) pour suivre les mises à jour mineures automatiquement. Pour une version figée, utilisez :26.5.2 par exemple. Consultez les release notes pour la dernière version.

Accéder à la console d’administration

1. Ouvrez votre navigateur à l’adresse http://localhost:8080

2. Cliquez sur Administration Console

3. Connectez-vous avec les identifiants définis au démarrage :

   • Username : admin
   • Password : admin

4. Vous arrivez sur le Master Realm — l’espace d’administration global

Le Master Realm

Le Master Realm est réservé à l’administration de Keycloak lui-même. Ne créez pas vos utilisateurs et applications ici. Dans le module suivant, vous apprendrez à créer un realm dédié à vos applications.

Variables de configuration essentielles

Keycloak se configure via des variables d’environnement (préfixées KC_) ou des options CLI (préfixées --).

Base de données

Variable	Description	Exemple
KC_DB	Type de base de données	postgres, mysql, mariadb
KC_DB_URL	URL JDBC de connexion	jdbc:postgresql://host:5432/db
KC_DB_USERNAME	Utilisateur de la base	keycloak
KC_DB_PASSWORD	Mot de passe	secret

Glissez pour voir

Administration initiale

Variable	Description
KC_BOOTSTRAP_ADMIN_USERNAME	Nom de l’admin initial
KC_BOOTSTRAP_ADMIN_PASSWORD	Mot de passe admin initial

Glissez pour voir

Variables dépréciées

Les variables KEYCLOAK_ADMIN et KEYCLOAK_ADMIN_PASSWORD sont dépréciées depuis Keycloak 26. Utilisez KC_BOOTSTRAP_ADMIN_*. Voir le guide de migration.

Réseau

Variable	Description	Exemple
KC_HOSTNAME	Hostname public	localhost, auth.example.com
KC_HTTP_PORT	Port HTTP	8080

Glissez pour voir

Fonctionnalités

Variable	Description	Exemple
KC_HEALTH_ENABLED	Endpoints /health/*	true
KC_METRICS_ENABLED	Métriques Prometheus	true
KC_LOG_LEVEL	Niveau de log	INFO, DEBUG

Glissez pour voir

Commandes utiles

Gestion des conteneurs

# Démarrer
docker compose up -d

# Arrêter
docker compose down

# Voir les logs
docker compose logs -f keycloak

# Redémarrer Keycloak
docker compose restart keycloak

# Supprimer tout (y compris les données)
docker compose down -v

État et diagnostic

# Vérifier que Keycloak répond
curl -I http://localhost:8080/health/ready

# Voir l'état des conteneurs
docker compose ps

Dépannage

Symptôme	Cause probable	Solution
Connection refused (DB)	PostgreSQL non démarré	Attendre le healthcheck ou docker compose restart
FATAL: password authentication failed	Mauvais credentials DB	Vérifier les variables KC_DB_*
Port already in use	Port 8080 occupé	Utiliser un autre port : 8180:8080
Page blanche au login	Navigateur cache	Ctrl+F5 ou mode navigation privée

Glissez pour voir

Réinitialiser complètement

Pour repartir de zéro (supprime toutes les données) :

docker compose down -v
docker compose up -d

À retenir

• Docker Compose est la méthode recommandée pour la formation
• Mode start-dev = développement uniquement (pas de TLS, pas de prod)
• PostgreSQL pour la persistance des données
• Variables KC_BOOTSTRAP_ADMIN_* pour créer l’admin initial (dépréciées : KEYCLOAK_ADMIN*)
• Console admin : http://localhost:8080 → Administration Console
• Master Realm : réservé à l’administration, ne pas y créer d’applications

Prochaines étapes

Administration Keycloak Créez des realms, gérez les utilisateurs, groupes et rôles.

OpenID Connect — Les fondamentaux Comprenez OIDC avant de configurer des clients.

Ressources

• Documentation officielle : keycloak.org/documentation
• Release notes : keycloak.org/docs/latest/release_notes
• Guide conteneurs : keycloak.org/server/containers
• Guide de migration : keycloak.org/docs/latest/upgrading

×

📖 Voir la documentation →