TL;DR — Résumé Rapide
Guide complet Keycloak : installation Docker, configuration des realms, clients OpenID Connect et SAML, fédération LDAP, RBAC et haute disponibilité.
Keycloak est la solution open-source leader en Gestion des Identités et des Accès (IAM) — elle fournit le Single Sign-On (SSO), MFA, connexion sociale, fédération LDAP/Active Directory et une autorisation fine-grained via OpenID Connect, OAuth 2.0 et SAML 2.0. Ce guide couvre l’installation avec Docker Compose, la configuration des realms, le RBAC, la fédération d’identités et le clustering haute disponibilité.
Prérequis
- Docker 25+ et Docker Compose v2 (ou cluster Kubernetes pour l’installation avec operator).
- PostgreSQL 15+ pour la production (H2 intégré est réservé au développement).
- Proxy inverse (Nginx ou Traefik) pour la terminaison TLS en production.
- Notions de base sur OAuth 2.0 (client, flux, tokens).
Architecture de Keycloak
Keycloak organise tout en realms — domaines de sécurité isolés :
| Concept | Description |
|---|---|
| Realm | Tenant isolé. Contient utilisateurs, clients, rôles et groupes |
| Client | Application enregistrée pour utiliser Keycloak |
| Utilisateur | Identité dans le realm (locale ou fédérée) |
| Rôle | Étiquette de permission. Rôles de realm ou rôles de client |
| Groupe | Collection d’utilisateurs avec rôles hérités |
| Fournisseur d’identité | IdP externe (Google, GitHub, SAML, LDAP) |
| Flux d’authentification | Pipeline configurable : login, OTP, WebAuthn |
Le realm master est le super-admin — utilisez-le uniquement pour gérer d’autres realms, jamais pour les utilisateurs d’application.
Étape 1 : Installer Keycloak avec Docker Compose
version: "3.9"
services:
postgres:
image: postgres:15
environment:
POSTGRES_DB: keycloak
POSTGRES_USER: keycloak
POSTGRES_PASSWORD: changeme
volumes:
- postgres_data:/var/lib/postgresql/data
keycloak:
image: quay.io/keycloak/keycloak:24.0
command: start
environment:
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://postgres/keycloak
KC_DB_USERNAME: keycloak
KC_DB_PASSWORD: changeme
KC_HOSTNAME: auth.exemple.com
KC_PROXY: edge
KEYCLOAK_ADMIN: admin
KEYCLOAK_ADMIN_PASSWORD: adminpass
ports:
- "8080:8080"
depends_on:
- postgres
volumes:
postgres_data:docker compose up -d
# Accédez à la Console d'administration sur http://localhost:8080Étape 2 : Configuration du Realm
| Paramètre | Valeur recommandée |
|---|---|
| Nom d’affichage | Nom de votre marque |
| Thème de connexion | keycloak ou personnalisé |
| Exiger SSL | external requests (production) |
| Délai d’inactivité SSO | 30 minutes |
| Durée du token d’accès | 5 minutes |
Configurez SMTP dans Paramètres du Realm → Email pour les e-mails de réinitialisation de mot de passe.
Étape 3 : Configuration des Clients OpenID Connect
Clients → Créer un client :
- Type de client : OpenID Connect
- Client ID :
myapp-client - Authentification client : Activée (confidentiel) pour les apps serveur ; Désactivée (public) pour les SPA
- URIs de redirection valides :
https://myapp.exemple.com/callback - Web origins :
https://myapp.exemple.com
Clients Confidentiels vs Publics
| Caractéristique | Confidentiel | Public |
|---|---|---|
| Possède un secret | Oui | Non |
| Cas d’utilisation | Serveur (Node, .NET, Python) | SPA, app mobile |
| Flux de code auth | Avec secret | Avec PKCE |
Étape 4 : Contrôle d’Accès Basé sur les Rôles (RBAC)
# Créer un rôle de realm avec kcadm.sh
kcadm.sh config credentials \
--server http://localhost:8080 \
--realm master \
--user admin --password adminpass
kcadm.sh create roles -r myapp -s name=app-admin
kcadm.sh create roles -r myapp -s name=app-userFlux recommandé : Rôles → Groupes → Utilisateurs. Assignez les rôles aux groupes et ajoutez les utilisateurs aux groupes.
Les rôles composites regroupent d’autres rôles : créez superutilisateur et ajoutez app-admin et app-user comme composites.
Étape 5 : Fédération d’Identités
Connexion Sociale (Google, GitHub, Microsoft)
Fournisseurs d’identité → Ajouter un fournisseur → Google :
- Créez une app OAuth 2.0 dans Google Cloud Console.
- Renseignez le Client ID et le Client Secret de Google dans Keycloak.
- URI de redirection :
https://auth.exemple.com/realms/myapp/broker/google/endpoint.
Fédération LDAP / Active Directory
| Paramètre | Valeur |
|---|---|
| Fournisseur | Active Directory |
| URL de connexion | ldap://ad.corp.exemple.com |
| Bind DN | CN=svc-keycloak,OU=ComptesService,DC=corp,DC=exemple,DC=com |
| DN des utilisateurs | OU=Utilisateurs,DC=corp,DC=exemple,DC=com |
| Mode de synchronisation | FORCE |
Exécutez Synchroniser tous les utilisateurs pour importer les utilisateurs AD.
Étape 6 : Flux d’Authentification et MFA
TOTP et WebAuthn
Pour TOTP : Authentification → Flux → browser → Dupliquer → Ajouter Formulaire OTP comme REQUIS.
Pour WebAuthn/Passkeys (Keycloak 22+) :
- Authentification → Politiques → Politique WebAuthn — définissez le domaine comme
Relying Party ID. - Ajoutez Authentificateur WebAuthn au flux navigateur.
Haute Disponibilité
environment:
KC_CACHE: ispn
KC_CACHE_STACK: jdbc-ping
KC_DB: postgres
KC_DB_URL: jdbc:postgresql://pgpool/keycloak- Activez les sessions sticky sur le répartiteur (cookie
AUTH_SESSION_ID). - Endpoint de santé :
GET /health/ready.
Keycloak vs Alternatives
| Fonctionnalité | Keycloak | Authentik | Authelia | Auth0 | Okta | FusionAuth |
|---|---|---|---|---|---|---|
| Open-source | Oui | Oui | Oui | Non | Non | Partiel |
| Auto-hébergé | Oui | Oui | Oui | Non | Non | Oui |
| SAML 2.0 | Oui | Oui | Non | Oui | Oui | Oui |
| Fédération LDAP | Oui | Oui | Non | Oui | Oui | Oui |
| Autorisation fine | Oui (UMA) | Non | Non | Oui (payant) | Oui (payant) | Partiel |
| Complexité | Haute | Moyenne | Faible | Faible | Faible | Moyenne |
Résolution de Problèmes
| Problème | Solution |
|---|---|
| ”Invalid redirect_uri” | Vérifiez les URIs de redirection — correspondance exacte requise |
| ”Client secret not valid” | Régénérez le secret dans Clients → Identifiants |
| Boucle de connexion | Vérifiez que KC_HOSTNAME correspond à l’URL réelle |
| E-mail non envoyé | Vérifiez SMTP dans Paramètres du Realm → Email |
| Utilisateurs LDAP non synchronisés | Vérifiez les identifiants de bind et exécutez une synchronisation manuelle |
Résumé
- Les realms isolent les tenants — utilisez toujours un realm dédié pour les applications.
- Les clients confidentiels utilisent des secrets ; les publics utilisent PKCE.
- Les groupes avec rôles permettent de scaler le RBAC — évitez d’assigner des rôles directement aux utilisateurs.
- La synchronisation LDAP en mode FORCE maintient AD comme source faisant autorité.
- Utilisez
KC_CACHE=ispnavecjdbc-pingpour la HA sans dépendances supplémentaires.