Le découpage en realms

Le realm est l’unité d’isolement de Keycloak (voir le cours 1). Combien en créer, et selon quel critère, est la première vraie décision d’architecture. Elle conditionne le SSO, la reprise des comptes, les politiques de sécurité et l’administration. Elle se défait mal : une fois les applications raccordées et les comptes repris, changer de realm revient à refaire une partie du raccordement. Ce cours donne les éléments pour trancher et pour justifier le choix.

Ce que porte un realm

Tout ce qui suit est défini une fois par realm et s’applique à tous ses clients :

• les utilisateurs, leurs credentials et le user profile ;
• les sessions SSO et leurs durées (inactivité, durée maximale) ;
• la politique de mots de passe et la protection contre la force brute ;
• les sources d’utilisateurs (fédération LDAP, User Storage) et les identity providers ;
• les thèmes par défaut (connexion, compte, e-mail, administration) ;
• les clés de signature et l’émetteur des jetons ;
• la configuration SMTP, les événements et leur conservation ;
• l’administration : rôles du client realm-management, permissions fines.

Deux realms ne partagent ni utilisateurs ni sessions. Un même individu présent dans deux realms y a deux comptes, deux identifiants techniques et deux mots de passe. Le seul pont natif est le brokering : un realm peut déclarer l’autre comme fournisseur d’identité OIDC. On obtient alors une forme de SSO, mais au prix de deux comptes liés et d’un écran supplémentaire à la première connexion.

Ce qui se règle par client, sans créer de realm

Beaucoup de demandes « il nous faut un realm » portent en fait sur des réglages disponibles au niveau du client :

La surcharge de flux se voit dans la représentation du client :

{
  "clientId": "portail-sensible",
  "attributes": {
    "login_theme": "theme-portail",
    "minimum.acr.value": "renforce"
  },
  "authenticationFlowBindingOverrides": {
    "browser": "6a30d2b6-df6a-4c93-b30a-f9c2038ed26d"
  }
}

Ce qui ne se règle pas par client : la politique de mots de passe, la force brute, le user profile, les required actions disponibles, les sources d’utilisateurs, les durées maximales de session SSO. Si deux populations ont besoin de valeurs différentes pour ces réglages, c’est un argument fort pour deux realms.

Organizations : une troisième voie

Depuis Keycloak 26.0, Organizations est supporté. Dans un même realm, une organisation regroupe des membres, déclare un ou plusieurs domaines e-mail et peut être associée à un fournisseur d’identité. À la connexion, l’utilisateur saisit son e-mail et Keycloak le route vers l’IdP de son organisation. Un claim organization peut être ajouté aux jetons via le client scope du même nom.

La fonction évolue vite dans la branche 26 : gestion des invitations (26.5), groupes propres à chaque organisation (26.6), délégation de l’administration d’une organisation (26.7), IdP partagé entre organisations (26.8). La version mineure réellement déployée compte donc beaucoup. Organizations est approfondi au cours 8. Retenez ici qu’avant de proposer un realm par partenaire, il faut regarder si une organisation par partenaire suffit.

Administration et délégation

L’administration suit aussi le découpage. Les droits d’un realm sont portés par les rôles de son client realm-management : donner manage-users à l’équipe support des usagers ne lui ouvre que ce realm. Avec un realm par population, chaque équipe gestionnaire reçoit naturellement son périmètre.

Dans un realm unique, la délégation passe par les permissions fines d’administration, refondues et supportées depuis Keycloak 26.2 : elles permettent par exemple de limiter une équipe à la gestion des membres d’un groupe. C’est plus fin, mais plus long à concevoir et à auditer. Si l’argument principal pour séparer deux populations est « deux équipes différentes les administrent », comparez les deux options avant de trancher (cours 8).

Le coût d’un grand nombre de realms

La documentation ne fixe pas de nombre maximal de realms. Mais chaque realm ajoute :

• de l’administration : clients, flux, thèmes, politiques et mappers à dupliquer et à maintenir cohérents ;
• de la charge : caches, clés, et dans le realm master un client d’administration par realm, dont les rôles s’ajoutent au rôle admin. Des retours d’expérience communautaires font état de ralentissements de la console et des démarrages à partir de quelques centaines de realms ;
• de la friction pour l’usager : un compte et un mot de passe par realm, pas de SSO sans brokering.

Un hébergeur peut aussi imposer ses propres limites (nombre de realms par offre, volumétrie). C’est un point à vérifier avec lui avant d’écrire le document d’architecture.

Trois options comparées

En pratique, la plupart des architectures retiennent un realm par population quand les exigences de sécurité ou de source d’identité diffèrent réellement (agents fédérés à un annuaire, usagers en auto-inscription), et un realm unique sinon. Le realm par application est l’exception à justifier.

Une grille pour décider

Posez ces questions, dans cet ordre :

1. Qui sont les populations ? Pour chacune : source de vérité, volume, mode d’inscription.
2. Doivent-elles partager le SSO ? Si un même individu circule entre leurs applications, un realm commun s’impose ou le brokering devient nécessaire.
3. Leurs politiques diffèrent-elles ? Mots de passe, MFA de base, durées de session, attributs obligatoires. Si oui pour les réglages non surchargeables par client, séparez.
4. Qui administre quoi ? Une équipe distincte par population plaide pour des realms distincts, ou pour des permissions fines.
5. Que demande chaque application au-delà ? Thème, MFA renforcé, jeton spécifique : presque toujours un réglage de client.
6. Que prépare-t-on pour la suite ? Nouvelles populations, partenaires, fédération d’identité nationale : anticiper un realm ou des organisations.

Pourquoi ce choix coûte cher à défaire

Changer un utilisateur de realm n’est pas une opération de Keycloak. Il faut exporter et réimporter le compte, avec ses credentials, ses liens vers les fournisseurs d’identité et ses facteurs. L’émetteur des jetons change, et souvent l’identifiant sub aussi. Chaque application qui stocke cet identifiant ou valide l’émetteur doit être reconfigurée, et toutes les sessions sont perdues.

Fusionner deux realms est encore plus délicat : doublons d’e-mails, conflits de noms de rôles et de clients, politiques à réconcilier. C’est pourquoi le découpage doit être décidé avant le raccordement massif des applications.

kcadm() { docker compose exec -T keycloak /opt/keycloak/bin/kcadm.sh "$@"; }
kcadm config credentials --server http://localhost:8080 --realm master --user admin --password admin

for R in agents usagers; do
  kcadm create realms -s realm=$R -s enabled=true
  kcadm create users -r $R -s username=test-$R -s email=test-$R@example.org \
    -s firstName=Test -s lastName=$R -s enabled=true
  kcadm set-password -r $R --username test-$R --new-password 'Academy2026!'
done

AC=$(kcadm get clients -r agents -q clientId=account-console --fields id --format csv --noquotes)
kcadm update clients/$AC -r agents -s 'attributes.login_theme=keycloak'

kcadm create authentication/flows/browser/copy -r agents -s newName=navigateur-compte
FID=$(kcadm get authentication/flows -r agents --fields id,alias --format csv --noquotes \
  | grep navigateur-compte | cut -d, -f1)
kcadm update clients/$AC -r agents -s "authenticationFlowBindingOverrides.browser=$FID"
kcadm get clients/$AC -r agents | grep -A2 authenticationFlowBindingOverrides