Keycloak : concepts, architecture et cas d'usage

30 min
Quiz · 6 questions

Par Stéphane Robert mis à jour le 15 octobre 2026

Améliorer cette page

Que voulez-vous signaler ?

L’issue s’ouvre déjà remplie avec le titre et l’adresse de cette page.

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.

Ce que vous allez apprendre

À la fin de cette leçon, 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

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)

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.

Les concepts fondamentaux (le "dico" Keycloak)

Ces concepts forment l'essentiel du vocabulaire 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

Configurations clés d'un client :

Redirect URIs : URLs autorisées après authentification
Web Origins : domaines web autorisés à appeler Keycloak depuis un navigateur (règle CORS)
Client authentication : activé = confidential, désactivé = public
Protocol : OIDC (par défaut) ou SAML

Une API qui se contente de valider des tokens, sans jamais initier de login, était autrefois déclarée en bearer-only. La documentation Keycloak actuelle qualifie ce type de déprécié : on déclare désormais un client ordinaire (souvent confidential) dont l'application ne déclenche simplement aucun flux de connexion.

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 après. 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`

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

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.

Un token est un jeton signé que l'application reçoit après la connexion. Il transporte des claims, c'est-à-dire des affirmations sur l'utilisateur (nom, email, rôles), et des scopes, qui bornent ce que l'application a le droit de demander. Le format détaillé est décrit dans OpenID Connect. Keycloak en émet trois sortes :

Token	Durée typique	Contenu
Access token	5 min (valeur par défaut d'un realm créé par vous)	Claims, rôles, scopes, envoyé aux APIs
Refresh token	30 min (borné par SSO Session Idle)	Permet d'obtenir un nouveau access token
ID token	5 min	Informations sur l'utilisateur (profil)

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.

Source · SVG

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.

Source · SVG

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.

Source · SVG

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).

Pour la mise en œuvre avec un second Keycloak dans le rôle du partenaire, et la prise de compte à éviter, voir Fédération entrante : déléguer la connexion à un IdP.

Architecture Keycloak (vue système)

Avant d'installer, visualisez l'architecture cible.

Les composants

Quatre briques composent l'architecture. PostgreSQL porte l'état durable : en mode développement, Keycloak démarre sur une base embarquée (H2) qui n'est pas prévue pour la production. Le reverse proxy, un serveur placé devant Keycloak qui reçoit le trafic HTTPS et le relaie en clair, n'est pas un simple confort : il termine le TLS (la « TLS termination » du tableau) 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)

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           # Ne pas déduire le hostname des requêtes
KC_PROXY_HEADERS=xforwarded       # Faire confiance aux headers du proxy

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.

Source · SVG

Production standard (VM)

Une seule instance suffit pour de nombreux 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.

Source · SVG

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. Le déploiement pas à pas est décrit dans Déployer Keycloak sur Kubernetes avec l'Operator.

Source · SVG

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 l'installation avec Docker, répondez à ces questions :

Combien de realms ?
- 1 realm par environnement (prod, staging) ?
- 1 realm par tenant (multi-tenant) ?
Quel protocole pour vos applications ?
- OIDC (moderne, recommandé) ?
- SAML (legacy, interop) ?
- Les deux ?
D'où viennent les identités ?
- Stockage local dans Keycloak ?
- Fédération LDAP/Active Directory ?
- Identity brokering (Google, Azure AD) ?
Où termine le TLS ?
- Au reverse proxy (recommandé) ?
- Dans Keycloak (end-to-end) ?
Quel est le hostname public ?
- auth.example.com ou keycloak.internal ?
- Cohérence avec les certificats TLS
Besoin de haute disponibilité ?
- Single instance suffit pour un lab
- Production = 2+ replicas + cache distribué
Stratégie de backup ?
- pg_dump pour la DB
- Export JSON des realms
- Rotation des clés de signature
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 ou confidential ; bearer-only est déprécié)
3 stratégies : IdP principal, fédération LDAP, identity brokering
Architecture prod : reverse proxy + TLS → Keycloak → PostgreSQL
Hostname/proxy : configuration critique, première cause de boucles de login et de redirect_uri cassées
Avant d'installer : répondre aux questions de la check-list

Contrôle de connaissances

Six questions tirées sur huit : le realm des applications, l'emplacement des rôles dans le jeton, ce que Keycloak ne remplace pas, le first broker login flow, les en-têtes du proxy et l'accès de secours.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin

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

Keycloak : concepts, architecture et cas d'usage

Ce que vous allez apprendre

Keycloak, c'est quoi ?

Ce que Keycloak apporte sans développement

Ce que Keycloak n'est pas

Les concepts fondamentaux (le "dico" Keycloak)

Realm

Client

Users (utilisateurs)

Groups (groupes)

Roles (rôles)

Sessions et tokens

Protocol Mappers et claims

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

Stratégie 1 : Keycloak comme IdP principal

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

Stratégie 3 : Identity Brokering

Architecture Keycloak (vue système)

Les composants

Pourquoi hostname et proxy sont critiques

Architectures types

Lab / développement

Production standard (VM)

Production HA (Kubernetes)

Gouvernance et modèle de droits

Moindre privilège

Break glass

Lien avec Authorization Services

Check-list avant d'installer

À retenir

Contrôle de connaissances

Contrôle de connaissances

Informations

Vérification

Score par domaine

Bilan

Points forts

Points faibles

À faire ensuite

Ressources