Keycloak : concepts, architecture et cas d'usage

Ce guide vous explique ce qu'est Keycloak, ses concepts fondamentaux, et l'architecture à prévoir avant de l'installer. À la fin, vous saurez si Keycloak répond à votre besoin, quels objets vous allez manipuler, et comment réfléchir "architecture" avant de lancer un conteneur.

En 30 secondes

• Keycloak = serveur SSO/IdP open-source (Red Hat)
• Protocoles : OIDC, OAuth 2.0, SAML 2.0
• Briques clés : Realm (tenant) → Clients (apps) → Users → Roles → Sessions
• Architecture prod : Reverse proxy + TLS → Keycloak → PostgreSQL
• 3 modes d'intégration : IdP principal, fédération LDAP, ou brokering vers IdP externe

Ce que vous allez apprendre

À la fin de ce module, vous saurez :

• Ce qu'est Keycloak et ce qu'il n'est pas
• Les concepts fondamentaux : realm, client, user, group, role, session
• Les 3 stratégies d'intégration : IdP principal, fédération LDAP, identity brokering
• L'architecture type à prévoir avant installation
• Les questions à se poser avant de démarrer

Prérequis théorique

Cette page suppose que vous connaissez les bases de l'IAM. Si ce n'est pas le cas, commencez par les Fondamentaux de la gestion des identités, notamment Bases de l'IAM et OpenID Connect.

Keycloak, c'est quoi ?

Keycloak est une solution de Single Sign-On (SSO) pour applications web et services REST. C'est un Identity Provider (IdP) qui centralise l'authentification et évite de recoder l'auth dans chaque application.

Ce que Keycloak apporte sans développement

L'intérêt de Keycloak tient à ce que vous n'avez pas à écrire : pages de connexion, réinitialisation de mot de passe, second facteur, gestion de session. Parcourez ce tableau en cochant mentalement ce que votre application recode aujourd'hui à la main ; chaque ligne cochée est du code que vous pourrez supprimer. Les deux dernières lignes, Identity Brokering et Authorization Services, sont celles qui décident souvent de l'adoption : ce sont aussi les plus longues à configurer correctement.

Fonctionnalité	Description
SSO	Une seule authentification pour toutes les applications d'un realm
Pages de login	Formulaires prêts à l'emploi, thèmes personnalisables
OIDC / OAuth 2.0	Protocoles modernes pour apps web, SPA, APIs
SAML 2.0	Interopérabilité avec applications legacy
Gestion des identités	Utilisateurs, groupes, rôles, attributs
MFA	TOTP (Google Authenticator), WebAuthn (FIDO2)
Fédération	Import d'utilisateurs depuis LDAP/Active Directory
Identity Brokering	Délégation de l'auth à un IdP externe (Google, Azure AD, etc.)
Authorization Services	Fine-grained access control (policies, permissions)

Glissez pour voir

Ce que Keycloak n'est pas

Keycloak est un IdP, pas un annuaire source. Il peut :

• Stocker des utilisateurs localement (base interne)
• Fédérer un LDAP/AD existant (lecture + sync)
• Broker vers un autre IdP (délégation)

Mais ce n'est pas un remplacement d'Active Directory. Dans une architecture entreprise, Keycloak est souvent devant un AD, pas à la place.

Keycloak ≠ Active Directory

Keycloak peut consommer un AD via LDAP, mais il ne gère pas les GPO, les trusts AD, ni les authentifications Kerberos natives. C'est un IdP moderne (OIDC/SAML), pas un contrôleur de domaine.

Les concepts fondamentaux (le "dico" Keycloak)

Comprendre ces concepts, c'est comprendre 80% de Keycloak. Chaque terme correspond à un objet dans l'interface d'administration.

Realm

Un realm est un espace isolé (tenant) contenant ses propres utilisateurs, clients, rôles et configurations. C'est l'unité d'isolation dans Keycloak.

Keycloak
├── master (realm d'administration)
├── prod (realm pour vos applications prod)
└── staging (realm pour les tests)

Bonnes pratiques :

• Le master realm est réservé à l'administration globale de Keycloak
• Créez un realm par environnement (prod, staging) ou par tenant
• Ne créez jamais vos utilisateurs applicatifs dans le master realm

Client

Un client représente une application ou API qui utilise Keycloak pour l'authentification.

Type de client	Usage	Exemples
Public	Application incapable de garder un secret	SPA, app mobile
Confidential	Application avec backend sécurisé	API, webapp server-side
Bearer-only	API consommant des tokens sans initier de login	Microservices

Glissez pour voir

Configurations clés d'un client :

• Redirect URIs : URLs autorisées après authentification
• Web Origins : Domaines autorisés pour CORS
• Client authentication : activé = confidential, désactivé = public
• Protocol : OIDC (par défaut) ou SAML

Pour créer un client et connecter une vraie application, voir le guide pratique Sécuriser une application avec Keycloak (OIDC).

Users (utilisateurs)

Un utilisateur appartient toujours à un realm et à un seul : le même identifiant dans deux realms désigne deux comptes sans aucun lien. C'est la conséquence directe de l'isolation vue plus haut, et la première surprise quand on crée un compte de test dans master en espérant s'en servir ailleurs. Les required actions méritent une attention particulière : elles forcent une étape à la prochaine connexion (changer le mot de passe, vérifier l'email, enrôler un OTP) et bloquent l'accès tant qu'elles ne sont pas satisfaites.

Chaque compte porte quatre familles d'informations :

• Identifiants : username, email
• Credentials : mot de passe, OTP, WebAuthn
• Attributs : données personnalisées (département, matricule, etc.)
• États : enabled, email verified, required actions

Groups (groupes)

Les groupes portent l'organisation, les rôles portent les droits. Séparer les deux évite le piège le plus courant en exploitation : attribuer des rôles utilisateur par utilisateur, puis ne plus savoir qui a quoi six mois plus tard. Un groupe hérite des rôles et attributs de son parent, ce qui permet de déclarer une politique une fois au niveau Engineering et de la voir s'appliquer à Backend et Frontend.

Concrètement, un groupe sert à :

• organiser les utilisateurs hiérarchiquement ;
• attribuer des rôles à un ensemble d'utilisateurs d'un seul geste ;
• propager des attributs aux sous-groupes par héritage.

Groupes
├── Employees
│   ├── Engineering
│   │   ├── Backend
│   │   └── Frontend
│   └── Marketing
└── Contractors

Roles (rôles)

Les rôles représentent les permissions. La distinction entre les deux types n'est pas cosmétique : un realm role finit dans le claim realm_access.roles du token, un client role dans resource_access.<client>.roles. Vos applications ne lisent donc pas au même endroit, et une API qui cherche ses rôles au mauvais endroit refusera l'accès à un utilisateur pourtant bien configuré. Par défaut, préférez les client roles : ils restent lisibles quand le nombre d'applications augmente.

Type	Description	Exemple
Realm role	Global au realm	admin, user
Client role	Spécifique à un client	myapp:editor, myapp:viewer

Glissez pour voir

Composite roles : un rôle peut inclure d'autres rôles (héritage).

Pattern recommandé

1. Créez des groupes basés sur l'organisation (équipes, départements)
2. Assignez des rôles aux groupes
3. Ajoutez des utilisateurs aux groupes
4. Les applications lisent les rôles dans le token

Sessions et tokens

Session SSO : lorsqu'un utilisateur se connecte, Keycloak crée une session. Tant que la session est active, l'utilisateur n'a pas à se reconnecter pour accéder aux autres applications du realm.

Tokens OIDC :

Token	Durée typique	Contenu
Access token	5 min	Claims, rôles, scopes, envoyé aux APIs
Refresh token	30 min	Permet d'obtenir un nouveau access token
ID token	5 min	Informations sur l'utilisateur (profil)

Glissez pour voir

Protocol Mappers et claims

Les mappers définissent ce qui est inclus dans les tokens. C'est le point de friction le plus fréquent en intégration OIDC : l'application attend un claim, Keycloak ne l'émet pas, et le message d'erreur côté application parle d'autorisation alors que le problème est un claim absent. Le réflexe de diagnostic est toujours le même : décoder le token reçu et comparer avec ce que le code lit.

Exemples de mappers :

• Ajouter les groupes de l'utilisateur dans le token
• Ajouter un attribut personnalisé (département, tenant ID)
• Renommer un claim (preferred_username → user)

Les 3 stratégies d'intégration de Keycloak

Avant d'installer, identifiez votre cas d'usage. Keycloak supporte 3 stratégies (combinables).

Stratégie 1 : Keycloak comme IdP principal

C'est la configuration la plus simple à mettre en route et la plus exigeante à exploiter : Keycloak devient la source de vérité des identités, donc la sauvegarde de PostgreSQL et la rotation des clés de signature deviennent des sujets critiques. Sur le schéma, notez qu'aucune flèche ne sort vers un annuaire externe : si la base est perdue, les comptes le sont aussi.

Cas d'usage : nouvelles applications, pas d'annuaire existant, ou applications SaaS internes.

Où sont les users : dans la base de données Keycloak (PostgreSQL).

Stratégie 2 : Fédération LDAP/Active Directory

Ici Keycloak ne détient plus les mots de passe : il les délègue à l'annuaire à chaque connexion, ou importe les comptes selon le mode de synchronisation choisi. Le point à trancher dès la conception est la direction d'écriture : en lecture seule, toute création de compte passe par l'annuaire ; en écriture, Keycloak modifie l'annuaire et vous devez accorder les droits correspondants au compte de service LDAP.

Cas d'usage : entreprise avec Active Directory existant, vous voulez réutiliser les identités.

Où sont les users : dans LDAP/AD. Keycloak les synchronise (import complet ou à la demande).

Avantages : pas de double gestion des mots de passe, intégration avec l'existant.

Pour la mise en œuvre, voir Fédérer un annuaire LDAP ou AD avec Keycloak.

Stratégie 3 : Identity Brokering

Le brokering déplace l'authentification chez un tiers : Keycloak ne vérifie aucun mot de passe, il valide le token que l'IdP externe lui renvoie et en produit un nouveau pour vos applications. L'avantage est que vos applications ne connaissent toujours qu'un seul émetteur. Le point de vigilance porte sur le first broker login flow, l'enchaînement qui décide quoi faire quand l'utilisateur arrive pour la première fois : créer un compte local, le rattacher à un compte existant par email, ou refuser. Mal configuré, c'est une porte ouverte à la prise de contrôle de compte par simple homonymie d'adresse.

Cas d'usage :

• Social login : "Se connecter avec Google/GitHub/GitLab"
• Fédération B2B : vos clients ont leur propre IdP (Azure AD)
• Consolidation : un Keycloak devant plusieurs IdP

Où sont les users : chez le provider externe. Keycloak broker l'authentification et peut créer une entrée locale (account linking).

Combinaison des stratégies

Vous pouvez combiner les 3 :

• Utilisateurs internes → fédération LDAP
• Partenaires → identity brokering vers leur IdP
• Utilisateurs externes → création locale + MFA

Les trois sources cohabitent dans le même realm et alimentent les mêmes tokens : vos applications n'ont qu'un émetteur à connaître, quelle que soit la provenance de l'utilisateur.

Architecture Keycloak (vue système)

Avant d'installer, visualisez l'architecture cible.

Les composants

Quatre briques suffisent, et une seule est réellement optionnelle. PostgreSQL porte l'état durable : sans base externe, Keycloak démarre sur une base embarquée qui n'est pas supportée en production. Le reverse proxy n'est pas un simple confort, c'est lui qui termine le TLS et injecte les en-têtes dont Keycloak se sert pour construire ses URLs publiques. Infinispan est embarqué par défaut ; vous ne le configurez que le jour où vous passez à plusieurs instances.

Composant	Rôle
Keycloak	Serveur IdP (Quarkus, Java 21)
PostgreSQL	Base de données (users, realms, sessions)
Reverse proxy	TLS termination, headers, load balancing
Infinispan (embarqué)	Cache distribué (sessions, tokens)

Glissez pour voir

Pourquoi hostname et proxy sont critiques

Keycloak impose une configuration de hostname explicite en production. C'est une mesure de sécurité pour éviter les attaques par manipulation d'URL.

Conséquence : une mauvaise configuration = boucles de login, redirect_uri cassées, endpoints .well-known incorrects.

Variables critiques :

KC_HOSTNAME=auth.example.com      # URL publique
KC_HOSTNAME_STRICT=true           # Rejeter les autres hostnames
KC_PROXY_HEADERS=xforwarded       # Faire confiance aux headers du proxy

Proxy headers obligatoires

Si Keycloak est derrière un reverse proxy (Nginx, Traefik, Caddy), vous devez configurer KC_PROXY_HEADERS pour que Keycloak utilise les headers X-Forwarded-*. Sinon : mixed content, mauvaises URLs dans les tokens, etc.

Architectures types

Lab / développement

En lab, tout tient dans un docker compose : Keycloak écoute en clair sur le port 8080, PostgreSQL tourne à côté, et vous accédez à la console via localhost. C'est la seule situation où l'absence de TLS est acceptable, précisément parce que localhost est traité comme une origine sûre par les navigateurs. Ne transposez jamais ce montage tel quel sur une adresse accessible depuis le réseau.

Production standard (VM)

Une seule instance suffit pour la grande majorité des besoins internes. Le changement par rapport au lab n'est pas le nombre de machines mais la chaîne de confiance : le TLS s'arrête au proxy, Keycloak reste en clair derrière, et il doit apprendre du proxy quelle URL le navigateur a réellement utilisée. C'est tout l'objet des points ci-dessous.

Points clés :

• TLS termination au niveau du reverse proxy
• En-têtes X-Forwarded-* propagés à Keycloak
• KC_PROXY_HEADERS=xforwarded obligatoire
• Backups réguliers de PostgreSQL

Production HA (Kubernetes)

Passer à plusieurs replicas ne consiste pas à augmenter un compteur. Deux instances Keycloak doivent partager leurs sessions via Infinispan, sinon un utilisateur ballotté d'un pod à l'autre se retrouve déconnecté sans raison apparente. Les sticky sessions limitent le problème mais ne le remplacent pas : elles réduisent les échanges de cache, elles ne les rendent pas inutiles.

Points clés :

• Ingress avec TLS et sticky sessions
• Replicas Keycloak gérés par l'Operator Keycloak
• Infinispan pour le cache de sessions distribué
• PostgreSQL HA (Patroni, CloudNativePG, etc.)

Gouvernance et modèle de droits

Moindre privilège

Un IdP concentre par nature un pouvoir considérable : qui peut modifier un client peut modifier les redirect URIs, donc détourner les codes d'autorisation vers un domaine qu'il contrôle. Les trois règles ci-dessous visent toutes le même objectif, réduire ce que peut faire un compte compromis avant qu'on ne s'en aperçoive.

• Les utilisateurs ne devraient avoir que les rôles nécessaires
• Les clients confidentiels ne devraient pas avoir plus de scopes que requis
• L'admin console ne devrait pas être exposée publiquement

Break glass

Le jour où l'IdP tombe, tout ce qui dépend de lui tombe avec, y compris votre propre moyen de vous connecter pour le réparer. Un accès de secours au realm master doit donc exister hors des dépendances habituelles : ni SSO, ni annuaire fédéré, ni outil interne lui-même protégé par Keycloak. Testez-le périodiquement, un accès d'urgence jamais essayé n'en est pas un.

• Compte admin avec MFA
• Procédure de récupération documentée
• Accès via réseau restreint (VPN, bastion)

Lien avec Authorization Services

Les rôles répondent à « qui êtes-vous », les Authorization Services répondent à « avez-vous le droit de faire cette action sur cet objet précis ». La bascule vaut le coup quand vos règles dépendent de la donnée elle-même (le propriétaire d'un document, l'appartenance à un projet) et non plus seulement du profil. Le coût est réel : chaque décision devient un appel supplémentaire à Keycloak, et le modèle ci-dessous est à concevoir avant d'écrire la première policy.

• Resources : ce qui est protégé (endpoint, document)
• Scopes : actions possibles (read, write, delete)
• Policies : règles d'accès (role-based, group-based, time-based)
• Permissions : association resource + scope + policy

Pour ce contrôle d'accès fin, consultez le guide officiel Authorization Services.

Check-list avant d'installer

Avant de lancer docker run, répondez à ces questions :

1. Combien de realms ?

   • 1 realm par environnement (prod, staging) ?
   • 1 realm par tenant (multi-tenant) ?

2. Quel protocole pour vos applications ?

   • OIDC (moderne, recommandé) ?
   • SAML (legacy, interop) ?
   • Les deux ?

3. D'où viennent les identités ?

   • Stockage local dans Keycloak ?
   • Fédération LDAP/Active Directory ?
   • Identity brokering (Google, Azure AD) ?

4. Où termine le TLS ?

   • Au reverse proxy (recommandé) ?
   • Dans Keycloak (end-to-end) ?

5. Quel est le hostname public ?

   • auth.example.com ou keycloak.internal ?
   • Cohérence avec les certificats TLS

6. Besoin de haute disponibilité ?

   • Single instance suffit pour un lab
   • Production = 2+ replicas + cache distribué

7. Stratégie de backup ?

   • pg_dump pour la DB
   • Export JSON des realms
   • Rotation des clés de signature

8. Accès admin sécurisé ?

   • Réseau restreint (VPN, bastion)
   • MFA pour les admins
   • Hostname admin séparé (optionnel)

À retenir

• Keycloak = IdP/SSO open-source (OIDC, SAML, LDAP, MFA)
• Realm = tenant isolé (ne pas utiliser master pour les apps)
• Client = application déclarée (public, confidential, bearer-only)
• 3 stratégies : IdP principal, fédération LDAP, identity brokering
• Architecture prod : reverse proxy + TLS → Keycloak → PostgreSQL
• Hostname/proxy : configuration critique, source de 80% des problèmes
• Avant d'installer : répondre aux questions de la check-list

Prochaines étapes

Installer Keycloak Déployer Keycloak en conditions réelles : reverse proxy, TLS et base PostgreSQL.

Administrer Keycloak Gérer les realms, les clients et les utilisateurs au quotidien.

Sécuriser une application (OIDC) Créer un client, gérer les redirect URIs, activer PKCE et valider les tokens.

Fédérer un annuaire LDAP/AD Brancher Keycloak sur un annuaire existant sans dupliquer les mots de passe.

Plan de formation Keycloak Le parcours complet : 4 axes (Installation, Intégration, Sécurité, Exploitation) et ses modules pratiques.

Ressources

• Server Administration Guide, documentation officielle
• Configuring Keycloak for production, exigences prod
• Configuring the hostname, configuration hostname (critique)
• Configuring a reverse proxy, headers et ports
• Authorization Services Guide, fine-grained access

×

📖 Voir la documentation →