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-user

Flux 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 :

  1. Créez une app OAuth 2.0 dans Google Cloud Console.
  2. Renseignez le Client ID et le Client Secret de Google dans Keycloak.
  3. 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+) :

  1. Authentification → Politiques → Politique WebAuthn — définissez le domaine comme Relying Party ID.
  2. 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=ispn avec jdbc-ping pour la HA sans dépendances supplémentaires.

Articles Connexes