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 “out of the box”

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

Users (utilisateurs)

Les utilisateurs vivent dans un realm. Chaque utilisateur possède :

• 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 sont des collections d’utilisateurs. Ils permettent :

• D’organiser les utilisateurs hiérarchiquement
• D’attribuer des rôles à un ensemble d’utilisateurs
• De propager des attributs (héritage)

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

Roles (rôles)

Les rôles représentent les permissions. Deux types :

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 nerf de la guerre en intégration OIDC.

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

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

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.

Stratégie 3 : Identity Brokering

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

C’est la force de Keycloak : un IdP pour les gouverner tous.

Architecture Keycloak (vue système)

Avant d’installer, visualisez l’architecture cible.

Les composants

Composant	Rôle
Keycloak	Serveur IdP (Quarkus, Java 17+)
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

Production standard (VM)

Points clés :

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

Production HA (Kubernetes)

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

• 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

Prévoyez un accès d’urgence au realm master :

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

Lien avec Authorization Services

Pour du fine-grained access control (RBAC avancé, ABAC), Keycloak propose les Authorization Services :

• 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

Ce sujet est couvert dans le module K2-03 — 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

Prochaine étape

Plan de formation à Keycloak Découvrez le plan complet de la formation Keycloak : 4 parcours (Installation, Intégration, Sécurité, Exploitation) avec 10 modules pratiques pour maîtriser Keycloak de A à Z.

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 →