Aller au contenu principal

Ressources

Extensions Keycloak en production : choisir le bon SPI, le livrer et survivre aux mises à jour

Extensions Keycloak en production : quel SPI choisir, comment livrer le JAR dans une image optimisée et tester chaque version avant la mise à jour.

Par , publié le · 25 min de lecture

Base d'expérience : Méthode et documentation officielle de Keycloak 26.7.4 (guides et code au tag 26.7.4) ; authenticators personnalisés, protocol mappers, event listeners, user storage et thèmes construits ou exploités en production par CTN Solutions, déclarés par le propriétaire le 27/09/2026, généralisés sans nom ni chiffre client.

Relecture factuelle : Claude Code (revue indépendante déléguée par Corentin Mas, 28/09/2026), le

Écrire un authenticator, un mapper de jetons ou un thème pour Keycloak est la partie courte du travail. Le JAR s'exécute ensuite dans le processus du serveur, sans isolation, sur des interfaces que le projet peut modifier à chaque version mineure ; il doit entrer dans une image reconstruite, se déployer sans couper l'authentification et être retesté à chaque mise à jour. Catalogues et documentation de référence disent quelles interfaces existent, rarement comment vivre avec.

Ce guide tranche les questions dans l'ordre où elles se posent : une configuration suffit-elle, quelle interface de fournisseur de service (SPI, Service Provider Interface) retenir, comment livrer le JAR dans une image optimisée sur Kubernetes, comment tester avant une version mineure, puis comment exploiter et retirer une extension. Il couvre aussi l'extension communautaire qui ajoute le protocole CAS (Central Authentication Service).

Faits datés

Cette lecture est établie sur Keycloak 26.7.4, publiée le 16 septembre 2026 et dernière version disponible au , dans la branche 26.7 sortie le 9 juillet 2026 ; aucune version 27 n'est publiée à cette date. Les guides officiels, le code du serveur au tag 26.7.4 et les dépôts tiers cités ont été vérifiés le ; sur une autre version, ce sont les sources de cette version qui font foi.

Vérifié le

Avant d'écrire du Java : configuration, flux ou extension ?

La documentation de configuration des providers pose le cadre : un chargeur de classes unique, des JAR du dossier providers prioritaires sur les bibliothèques intégrées, aucun bac à sable. Un provider peut faire tout ce que peut le processus du serveur, dont accéder directement à la base et lire toute la configuration, secrets compris. Une extension est donc une dépendance de sécurité exécutée avec les droits du serveur d'identité.

Le rythme des versions fixe le coût récurrent. D'après la politique de publication du projet, les versions mineures sortent environ quatre fois par an ; seule la dernière reçoit les correctifs, sécurité comprise, et la précédente cesse d'être supportée dès la sortie d'une nouvelle mineure. Une extension impose donc une campagne de tests par version mineure et une reconstruction d'image à chaque correctif.

Keycloak 26.7 couvre sans code une part des besoins qui motivaient autrefois une extension : step-up, passkeys, organisations et workflows y sont activés par défaut, et le profil utilisateur déclaratif est toujours actif depuis la version 24. Les providers JavaScript (fonctionnalité scripts) restent en préversion, désactivés par défaut : ce n'est pas une voie de production.

Besoin, réponse sans code disponible en Keycloak 26.7 et condition qui justifie une extension
BesoinRéponse sans code en 26.7Une extension se justifie quand
Second facteur selon le rôle, le client ou un attributSous-flux conditionnel : Condition - User Role, Condition - User Attribute, Condition - client scope, Condition - credential, exécutions Deny Access et Allow AccessLa décision dépend d'un système externe interrogé pendant la connexion
Envoyer vers le bon fournisseur d'identitéOrganisations : identifiant d'abord, redirection quand le domaine de l'adresse e-mail correspondLe routage dépend d'autre chose que ce domaine
Ajouter une information dans un jetonMappers intégrés : valeur fixe, attribut utilisateur, note de session, renommage de rôleLa valeur est calculée ou vient d'une source extérieure
Collecter et valider des attributsProfil utilisateur déclaratif et ses validateursLa validation appelle une règle métier externe
Agir à la création d'un compte ou après une inactivitéWorkflows : déclencheurs comme user-created, étapes add-required-action, grant-role, notify-user, disable-user, immédiates ou planifiéesL'action doit prévenir un système externe
Utiliser un annuaire existantFédération LDAP ou Active Directory intégréeLe magasin n'est pas un annuaire LDAP et ne peut pas être migré

La colonne du milieu se versionne avec la configuration du royaume, par les outils décrits dans « Piloter la configuration Keycloak en GitOps : adoption, dérive et suppression de champs », et traverse les versions sans recompilation.

Quel SPI pour quel besoin

CTN Solutions a construit ou exploité en production des authenticators personnalisés, des protocol mappers, des event listeners, des fournisseurs de stockage d'utilisateurs et des thèmes. Les recommandations qui suivent sont généralisées et ne décrivent aucun déploiement client.

Un SPI se compose d'une fabrique (ProviderFactory), instanciée une fois par serveur, et d'un provider qu'elle crée pour chaque requête. La fabrique est déclarée dans META-INF/services/<interface de la fabrique>, et son getId() devient l'identifiant que le royaume enregistre. Le statut indiqué est celui que déclare isInternal() au tag 26.7.4.

Pour chaque besoin, le SPI Keycloak, les interfaces à implémenter, le statut public ou interne au tag 26.7.4 et le risque principal en production
BesoinSPI (identifiant)À implémenterStatut en 26.7.4Risque principal en production
Étape de connexionauthenticatorAuthenticatorFactory, AuthenticatorInterneSi le provider manque, l'étape échoue à chaque connexion
Action imposée après l'authentificationrequired-actionRequiredActionFactory, RequiredActionProviderInterneIdentifiant enregistré dans le royaume ; getMaxAuthAge() déprécié en 26.3
Claim calculé dans un jetonprotocol-mapperAbstractOIDCProtocolMapper et une interface par jetonInterne ; classe de base dans keycloak-servicesUne seule instance pour toutes les requêtes
Réaction à un événementeventsListenerEventListenerProviderFactory, EventListenerProviderInterneAppel synchrone, sur le chemin de chaque connexion
Utilisateurs dans un magasin externestorageUserStorageProviderFactory, puis UserLookupProvider, CredentialInputValidator, UserQueryProvider selon les capacitésPublicUne panne du magasin fait échouer la connexion, sans bascule
ApparenceThème en fichiers ; themeSelector ou themeResource si du code est nécessaireMETA-INF/keycloak-themes.json, gabarits FreeMarkertheme interne ; themeSelector et themeResource publicsGabarits exécutés par le serveur ; évolution des thèmes parents
Nouveau protocole clientlogin-protocolLoginProtocolFactory, LoginProtocolInterneCouplage fort au code du serveur

Points d'accroche des SPI dans une connexion Keycloak

Le parcours d'une connexion, de la demande de l'application à la réponse, avec l'endroit où chaque famille d'extensions intervient.

Schéma défilable horizontalement ; sa version textuelle complète suit.

Lire le schéma sous forme textuelle
  1. L'application cliente demande une connexion en OpenID Connect ou SAML, intégrés, ou en CAS, apporté par une extension du SPI login-protocol.
  2. Le royaume exécute son flux d'authentification : authenticators, conditions, exécutions d'autorisation ou de refus.
  3. Pendant ces étapes, Keycloak cherche l'utilisateur dans son cache, puis dans sa base locale, puis auprès des fournisseurs de stockage par priorité, qui peuvent aussi valider le mot de passe.
  4. L'utilisateur authentifié passe les required actions en attente.
  5. Les protocol mappers construisent les claims du jeton ou de l'assertion, par ordre de priorité, puis la réponse part vers l'application.
  6. Les étapes produisent des événements, comme LOGIN ou LOGIN_ERROR, transmis de façon synchrone aux event listeners : un succès dans la transaction de la requête, une erreur par défaut dans une transaction séparée ouverte immédiatement.
  7. Le thème fournit les pages et les e-mails.
Modèle explicatif, sans donnée client, d'après le Server Developer Guide, le Server Administration Guide et le code de Keycloak au tag 26.7.4.

Authenticators et required actions

Le moteur de flux pose trois questions à un authenticator : lui faut-il un utilisateur déjà identifié (requiresUser()), l'utilisateur est-il configuré pour lui (configuredFor()), et que faire sinon (setRequiredActions(), appelée seulement si la fabrique renvoie vrai pour isUserSetupAllowed()). Pour un nouveau facteur, l'authenticator vérifie et la required action fait enrôler. Tout attribut utilisé pour établir l'identité doit être en lecture seule pour l'utilisateur, prévient le guide.

L'identifiant renvoyé par getId() est écrit dans chaque exécution de flux. Le renommer, ou retirer le JAR alors qu'un flux y fait référence, ne se voit qu'à l'exécution : le serveur lève Unable to find factory for AuthenticatorFactory quand une connexion atteint l'étape. Côté required action, la version 26.3 a déprécié getMaxAuthAge() au profit de getMaxAuthAge(KeycloakSession).

Protocol mappers

Un mapper OIDC étend en pratique AbstractOIDCProtocolMapper, qui vit dans keycloak-services, l'implémentation du serveur, et implémente une interface par destination (OIDCAccessTokenMapper, OIDCIDTokenMapper, UserInfoTokenMapper, TokenIntrospectionTokenMapper). ProtocolMapper est à la fois provider et fabrique : la même instance sert toutes les requêtes et ne doit porter aucun état lié à une requête. L'ordre d'application n'est pas non plus un réglage : chaque implémentation déclare getPriority(), la plus basse passant en premier. En 26.7, les post-traitements de réponse de jeton (SPI interne token-interceptor, interfaces TokenPostProcessor et TokenPostProcessorFactory) sont appelés selon ProviderFactory#order(), la valeur la plus haute en premier, alors que leur ordre était auparavant indéterminé.

Un claim calculé se paie à chaque émission de jeton, rafraîchissements compris : un mapper qui appelle un service externe le met sur le chemin critique de tout le royaume et exige un délai borné et un comportement d'échec explicite.

Event listeners

La Javadoc de EventListenerProvider pose la règle : onEvent s'exécute dans une transaction en cours et ne doit rien faire qui ne puisse être annulé. Une action non annulable, appel HTTP ou écriture de fichier, se diffère après validation par KeycloakTransactionManager#enlistAfterCompletion. Le code 26.7.4 précise deux cas : un événement de succès est transmis dans la transaction de la requête, alors qu'un événement d'erreur est transmis par défaut dans une transaction séparée, ouverte immédiatement. Dans les deux cas l'appel est synchrone : un listener lent ralentit chaque connexion. Une exception levée par un listener est capturée et journalisée sans bloquer la connexion. Un listener s'active royaume par royaume, sauf si sa fabrique déclare isGlobal(). Enfin, une exception levée par une transaction enregistrée « après validation » est relancée une fois la transaction principale validée, alors que ses écritures sont déjà en base : la publication différée doit capturer ses propres erreurs.

Stockage d'utilisateurs (fédération)

Sélection de thème mise à part, le SPI storage est le seul, parmi ceux décrits ici, que Keycloak déclare public. Un fournisseur n'implémente que les capacités de son magasin : UserLookupProvider pour la connexion, CredentialInputValidator pour vérifier un mot de passe, UserQueryProvider pour que la console liste et cherche les utilisateurs. Le choix structurant est l'import : copier l'utilisateur dans la base Keycloak à la première recherche soulage le magasin, mais chaque première connexion écrit en base et la synchronisation devient permanente.

Deux règles de ce mode sont à connaître avant la production. Si ImportedUserValidation.validate() renvoie null, l'utilisateur local est supprimé : une indisponibilité du magasin doit lever une erreur, jamais produire ce null. Et supprimer le fournisseur de stockage supprime tous les utilisateurs qu'il a importés. Pour une base externe, le guide recommande les sources de données supplémentaires de Keycloak plutôt qu'un pool ouvert par l'extension.

Thèmes

Un thème ne demande pas de Java. Il se déclare par theme.properties (parent, import), surcharge gabarits FreeMarker, feuilles de style et messages, et se livre de préférence en JAR avec un descripteur META-INF/keycloak-themes.json qui liste les thèmes et leurs types (login, account, admin, email, welcome). Le guide prévient qu'un gabarit malveillant peut exécuter du code avec les droits du processus Keycloak : l'écriture dans themes et dans les JAR de thème relève du même contrôle que les extensions Java. Pour les consoles, écrites en React, le projet publie @keycloak/keycloak-admin-ui et @keycloak/keycloak-account-ui sur npm ; le catalogue des extensions de keycloak.org cite aussi Keycloakify, outil communautaire.

Les options de développement qui désactivent les caches (--spi-theme--cache-themes=false et voisines) n'ont pas leur place en production. En 26.7, la fonctionnalité login:v2, le nouveau thème de connexion, est active par défaut, et l'ancien thème de connexion (login:v1) est déprécié : un thème qui l'étend repose sur une base appelée à disparaître.

« keycloak cas » : l'extension de protocole CAS communautaire

CAS ne fait pas partie des protocoles documentés par le guide d'administration de Keycloak. Il arrive par une extension communautaire référencée dans le catalogue des extensions de keycloak.org, jacekkow/keycloak-protocol-cas, sous licence Apache 2.0, qui implémente le SPI interne login-protocol et ajoute cas comme protocole de client. Le catalogue précise que ces extensions ne sont pas vérifiées par l'équipe Keycloak et sont maintenues par des tiers indépendants. État au :

  • Maintenance : une version publiée par version de Keycloak ; la 26.7.4 suit Keycloak 26.7.4, par une mise à jour automatique fusionnée le 17 septembre 2026, le lendemain de la sortie du serveur.
  • Compatibilité : l'extension est « testée contre la même version de Keycloak que la version du plugin », et le README demande de mettre à jour le JAR à chaque mise à jour du serveur.
  • Couverture : connexion, déconnexion et validation de tickets CAS 1.0, 2.0 et 3.0, Single Logout, réponses JSON et XML, attributs dans l'assertion ; la requête et la réponse SAML, optionnelles en CAS 3.0, manquent.
  • Configuration : le client est reconnu par ses URI de redirection ; l'URL CAS est https://<hôte>/realms/<royaume>/protocol/cas, suivie de /login ou /serviceValidate si l'application demande des URL séparées.
  • Couplage : au tag 26.7.4, le pom.xml dépend de keycloak-server-spi-private et de keycloak-services, et l'implémentation s'appuie largement sur le code OpenID Connect du serveur.

Conséquence d'exploitation : la publication de la version correspondante de l'extension conditionne chaque montée de version de Keycloak, correctif de sécurité compris.

Construire et livrer : du JAR à l'image optimisée

Le JAR et kc.sh build

Le guide du développeur fixe la base du projet Maven : importer keycloak-parent de la version visée en dependencyManagement, puis déclarer les modules Keycloak en portée provided. Les dépendances tierces absentes de la distribution se copient à côté du JAR dans providers. Faute de chargeur de classes isolé, une classe ou une ressource en conflit avec une bibliothèque intégrée pose problème : le guide cite un application.properties embarqué, qui fait échouer la reconstruction automatique une fois le JAR retiré.

kc.sh build fige ensuite le registre des providers : dans la distribution Quarkus, les fabriques sont découvertes à la construction, et le démarrage optimisé instancie la liste enregistrée. Ajouter, retirer ou remplacer un JAR impose donc une nouvelle construction. Les options qui choisissent ou activent un provider sont des options de construction : --spi-<spi>--provider=<id>, --spi-<spi>--provider-default=<id>, --spi-<spi>--<id>--enabled=<booléen>. Les propriétés propres au provider, --spi-<spi>--<id>--<propriété>, restent des options d'exécution lues dans init(Config.Scope). Le séparateur double est la forme recommandée depuis 26.3.

L'avertissement qui signale une extension bâtie sur un SPI interne, KC-SERVICES0047, est émis par l'étape Quarkus de construction, pas par le serveur démarré en mode optimisé : avec une image optimisée, il n'apparaît que dans la sortie de kc.sh build, jamais dans les journaux des pods. Conservée dans l'image, cette sortie permet à la CI de comparer à chaque livraison les lignes is implementing the internal SPI à une liste attendue, et de bloquer tout écart. L'avertissement ne concerne que les fabriques hors du paquet org.keycloak : une extension publiée sous ce paquet, comme l'extension CAS, n'y figure pas et doit être suivie par la liste des JAR de l'image.

# Référence synthétique pour Keycloak 26.7.4 : à adapter et relire avant usage
FROM quay.io/keycloak/keycloak:26.7.4 AS builder

# Options de construction, figées dans l'image
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
ENV KC_DB=postgres

# Extensions, dépendances et thèmes en JAR, versions épinglées
COPY --chown=keycloak:keycloak --chmod=644 providers/*.jar /opt/keycloak/providers/

# Horodatage fixe : sinon start --optimized peut refuser un JAR dont la date a changé
RUN touch -m --date=@1743465600 /opt/keycloak/providers/*
RUN /opt/keycloak/bin/kc.sh build > /opt/keycloak/kc-build.log 2>&1 \
    || (cat /opt/keycloak/kc-build.log && exit 1)

FROM quay.io/keycloak/keycloak:26.7.4
COPY --from=builder /opt/keycloak/ /opt/keycloak/
ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

Déployer avec le Keycloak Operator

L'opérateur démarre une image personnalisée (spec.image) en mode optimisé, sauf startOptimized: false. Sa documentation pose trois règles : les options de construction passées par la ressource sont ignorées avec une image personnalisée, health-enabled et metrics-enabled doivent être posées dans le Containerfile, et la version de Keycloak de l'image doit être alignée sur celle de l'opérateur.

Le point souvent découvert trop tard est la stratégie de mise à jour. Par défaut (RecreateOnImageChange), tout changement de nom ou d'étiquette d'image réduit le StatefulSet avant d'appliquer la nouvelle image : chaque version d'extension coupe l'authentification. Avec Auto, un Job évalue la compatibilité et l'opérateur fait une mise à jour progressive si la version de Keycloak reste identique ou passe à un correctif plus récent de la même branche major.minor. Explicit confie la décision au champ spec.update.revision. La condition RecreateUpdateUsed du statut indique la stratégie appliquée et sa raison.

# Référence synthétique : ressource Keycloak, opérateur 26.7
apiVersion: k8s.keycloak.org/v2beta1
kind: Keycloak
metadata:
  name: keycloak
spec:
  instances: 3
  image: <REGISTRE>/keycloak@sha256:<DIGEST>   # image optimisée, extensions incluses
  update:
    strategy: Auto                              # défaut : RecreateOnImageChange
  additionalOptions:                            # options d'exécution uniquement
    - name: spi-events-listener--mon-listener--endpoint
      value: 'https://<HOTE_INTERNE>/evenements'
  http:
    tlsSecret: <SECRET_TLS>
  hostname:
    hostname: <HOTE_PUBLIC>

Cette évaluation, confiée à kc.sh update-compatibility, compare la version, des fonctionnalités et des options de cache ou de base ; son guide ne décrit aucune analyse d'un JAR. Or l'ancienne et la nouvelle version de l'extension coexistent pendant une mise à jour progressive : une extension qui change le format d'une donnée partagée doit rester lisible par sa version précédente, ou être livrée avec une recréation assumée. Hors opérateur, la même commande sert en CI : metadata --file=<fichier> sur la configuration en production, check --file=<fichier> avec la nouvelle image, puis décision sur le code de sortie (0 : progressive possible ; 3 : arrêt complet requis).

Et avec Helm ?

La documentation de l'opérateur décrit une installation par OLM (Operator Lifecycle Manager) ou par kubectl apply -k, sans chart Helm. Les charts Helm listés dans le catalogue des extensions de keycloak.org sont communautaires. Le principe ne change pas : image personnalisée, start --optimized passé par command ou args, décision de mise à jour portée par le pipeline. Copier un JAR de provider par un conteneur d'initialisation reporte la construction au démarrage de chaque pod : l'image optimisée reste la voie à privilégier.

Le comportement du cluster pendant ces remplacements de pods (caches distribués, sessions, haute disponibilité) sort du cadre de ce guide. Sur une plateforme où cette chaîne n'existe pas encore, la construire fait partie d'une mise en production Kubernetes ouverte par étapes : image versionnée, stratégie de mise à jour décidée, retour arrière testé.

Survivre aux mises à jour : SPI internes, SPI publics et matrice de tests

La politique de publication de Keycloak borne la compatibilité : les garanties ne couvrent que les fonctionnalités supportées et les API publiques, et un correctif important ou de sécurité peut introduire une rupture dans n'importe quelle version.

Le code dit quelles API sont publiques. Au tag 26.7.4, le module keycloak-server-spi ne déclare que cinq SPI : hostname, localeSelector, localeUpdater, themeSelector et themeResource ; storage est lui aussi public. Presque tout le reste, dont authenticator, required-action, form-action, protocol-mapper, eventsListener, theme et login-protocol, est déclaré interne dans keycloak-server-spi-private. Une fabrique hors du paquet org.keycloak qui implémente un SPI interne déclenche KC-SERVICES0047: <id> (<classe>) is implementing the internal SPI <spi>. This SPI is internal and may change without notice. Pour la plupart des extensions, cet avertissement est la norme : chaque version mineure est potentiellement cassante.

Ce qui a changé dans la branche 26 et touche des extensions

Relevé non exhaustif du guide de montée de version :

Changements documentés par le guide de montée de version de 26.3 à 26.7 et extensions concernées
VersionChangement documentéExtensions concernées
26.3Options SPI à double tiret ; RequiredActionProvider.getMaxAuthAge() déprécié ; KeycloakSessionTask.useExistingSession suppriméeConfiguration de tout provider ; required actions
26.4SimpleHttp déplacé dans org.keycloak.http.simple ; API de UserSessionProvider simplifiée ; noms des fichiers de messages alignés sur ResourceBundleAppels HTTP sortants ; thèmes traduits
26.5Usage direct de org.keycloak.credential.UserCredentialManager déconseillé ; plus de HTML dans les messages du thème de connexionUser storage ; thèmes
26.6Méthodes en flux de UserSessionProvider, anciennes dépréciées pour suppression ; thèmes base abstraits ; politiques JavaScript soumises à scriptsCode qui parcourt les sessions ; thèmes ; scripts
26.7Transaction de session démarrable une seule fois ; REST asynchrone déconseillé ; KeycloakContext revu hors requête ; FreeMarker aux réglages 2.3.32 ; changesets des JpaEntityProvider personnalisés dans l'export de migration manuellePoints de terminaison REST ; traitements asynchrones ; thèmes ; entités JPA

Plusieurs lignes cassent le comportement sans casser la compilation : une transaction redémarrée, un contexte absent hors requête ou un gabarit qui dépendait des anciens réglages FreeMarker échouent à l'exécution. D'où une matrice de tests exécutée avant la montée de version.

Une matrice de tests par version

Le framework de test Keycloak, annoncé comme pleinement supporté à partir de 26.6.0, vise explicitement les extensions. Une classe annotée @KeycloakIntegrationTest démarre un serveur et injecte royaumes, clients et utilisateurs ; KeycloakServerConfig déploie l'extension par dependency(...) ou dependencyCurrentProject(). Le mode par défaut, distribution, lance la distribution comme processus externe. Le framework s'importe par la BOM keycloak-test-framework-bom, dont la version suit la propriété Maven keycloak.version ; une CI qui couvre deux versions exécute la suite une fois par valeur de cette propriété, en vérifiant dans les journaux la version réellement lancée.

Axes de la matrice de tests, valeurs minimales et vérifications attendues
AxeValeurs minimalesCe qui est vérifié
Version de KeycloakProduction (dernier correctif) et version visée ; version nocturne en optionCompilation sans nouvelle dépréciation ; suite d'intégration complète
Version de l'extensionProduction et candidate, qui coexistent pendant une mise à jour progressiveLecture croisée des données partagées
Base de donnéesLe moteur de production, pas H2Migrations des entités personnalisées ; requêtes d'un fournisseur de stockage
DémarrageImage optimisée, construite comme en productionProviders présents ; liste des SPI internes et liste des JAR attendues
ParcoursConnexion, rafraîchissement, déconnexion, enrôlement, pages de thème, e-mailsClaims du jeton décodé, événements reçus, rendu des pages

De l'extension à la production : tests par version, image et déploiement

La chaîne de livraison d'une extension, avec les trois points de contrôle qui renvoient au code ou à l'image précédente.

Schéma défilable horizontalement ; sa version textuelle complète suit.

Lire le schéma sous forme textuelle
  1. Le code de l'extension passe ses tests unitaires, puis ses tests d'intégration en mode distribution, sur la version de Keycloak en production et sur la version visée ; un échec renvoie au code.
  2. L'image est construite : JAR copiés dans providers, puis kc.sh build.
  3. La liste des SPI internes relevée à la construction et la liste des JAR de l'image sont comparées aux listes attendues ; tout écart renvoie au code.
  4. La même image passe en préproduction avec la même stratégie de mise à jour qu'en production, puis en production, épinglée par digest, via la ressource Keycloak en stratégie Auto.
  5. Connexions, claims et événements sont contrôlés : en cas d'écart, retour à l'image précédente, de même version de Keycloak ; sinon, cette image reste disponible pour le prochain retour arrière.
Modèle explicatif, sans donnée client, d'après la documentation du framework de test, le guide des images de conteneur et le guide des mises à jour progressives de l'opérateur Keycloak.

Avant chaque montée de version : chercher les classes importées par l'extension dans les notes de chaque version franchie, recompiler avec les dépréciations visibles, rejouer la matrice, vérifier que chaque extension tierce existe dans la version correspondante.

Exploiter une extension : journaux, métriques, user storage et retour arrière

Journaux, métriques et traces

Chaque extension journalise sous sa propre catégorie : --log-level-com.example.keycloak=debug prime sur --log-level, et --log-mdc-enabled=true ajoute le royaume et le client (kc.realmName, kc.clientId). Aucun jeton, secret ou attribut sensible ne doit y figurer, même en debug.

Le point /metrics de l'interface de gestion, sur le port 9000 par défaut, expose les métriques quand metrics-enabled est actif. --event-metrics-user-enabled=true compte connexions, échecs et rafraîchissements par royaume, et optionnellement par client (10 000 valeurs distinctes au plus par défaut pour clientId et error) : de quoi mesurer l'effet d'un authenticator sur les échecs sans code supplémentaire. TracingProvider, SPI interne, ouvre des spans dans les traces OpenTelemetry du serveur, qui couvrent déjà HTTP entrant, base, LDAP et HTTP sortant. Pour ses appels sortants, une extension gagne à utiliser le client HTTP du serveur (SPI connectionsHttpClient), réglable par options : 5 000 ms par défaut pour obtenir une connexion et pour l'inactivité du socket, pool de 128. Enfin, une fabrique qui implémente ServerInfoAwareProviderFactory peut publier des informations de fonctionnement, sa version par exemple, dans la page d'informations serveur de la console (getOperationalInfo()).

Performance d'un fournisseur de stockage

L'ordre de recherche fixe le profil de charge : cache utilisateur, base locale, puis fournisseurs par priorité. Le cache est local à chaque nœud, invalidé à l'échelle du cluster, et sa politique se règle par fournisseur : DEFAULT, NO_CACHE, EVICT_DAILY, EVICT_WEEKLY ou MAX_LIFESPAN. Si le magasin ne pagine pas, le fournisseur pagine lui-même (firstResult, maxResults). En panne, Keycloak ne bascule pas vers un autre fournisseur : la connexion échoue. Le guide recommande un compte d'administration local et, en incident, la désactivation du fournisseur, dont les utilisateurs importés restent consultables en lecture seule.

Retour arrière

Retirer une extension est une migration, pas un simple retour d'image : la configuration du royaume référence les identifiants des providers. Effet d'un provider absent, lu dans le code 26.7.4 :

Référence dans la configuration du royaume, effet si le provider a disparu et précaution de retrait
Référence dans le royaumeEffet si le provider a disparuPrécaution
Exécution d'un flux (authenticator)Erreur Unable to find factory for AuthenticatorFactory quand une connexion atteint l'étapeRetirer l'exécution avant le JAR
Mapper de protocoleMapper ignoré sans erreur : jeton émis sans le claimRetirer ou remplacer le mapper, puis contrôler les claims
Écouteur d'événementsErreur de journal registered, but provider not found ; connexions non bloquéesRetirer l'écouteur de la configuration du royaume
Fournisseur de stockageAvertissement Configured StorageProvider ... does not exist ; fournisseur ignoréDésactiver plutôt que supprimer : la suppression efface les utilisateurs importés
Entités JPA personnaliséesTables et changesets restent en basePrévoir une migration inverse distincte

Le mapper est le cas le plus dangereux, car silencieux : l'application reçoit des jetons valides mais incomplets. Le retour arrière le plus sûr reste l'image précédente épinglée par digest, de même version de Keycloak, que l'opérateur en Auto peut remettre sans recréer tous les pods.

Sources officielles et limites de lecture

Les comportements décrits ont été vérifiés le contre la documentation et le code de Keycloak au tag 26.7.4. Plusieurs points viennent du code et non des guides : statut de chaque SPI, étape qui émet KC-SERVICES0047, transmission des événements de succès et d'erreur, traitement des exceptions des event listeners et des transactions après validation, ordre des post-traitements de jeton, effet d'un provider absent. Ils peuvent changer sans note dédiée : le code de la version installée fait foi. Les informations sur l'extension CAS et sur le catalogue des extensions sont à revérifier dans leurs dépôts avant usage.

Cette lecture ne couvre pas les points de terminaison REST ni les entités JPA personnalisées, et n'évalue pas le code de l'extension CAS ni celui des charts Helm communautaires. La version majeure 27, non publiée au , retirera tous les usages de SHA-1 selon le guide de montée de version ; la conduite d'une montée de version majeure et le retour à une version antérieure de Keycloak sortent du cadre de cet article. Aucun chiffre de performance n'est donné : le coût d'un fournisseur de stockage ou d'un mapper dépend du magasin, du réseau et du volume de connexions.

Sources

  1. Release 26.7.4, dépôt keycloak/keycloak, publiée le 16/09/2026, https://github.com/keycloak/keycloak/releases/tag/26.7.4, consulté le 28/09/2026.
  2. Release 26.7.0, dépôt keycloak/keycloak, publiée le 09/07/2026, https://github.com/keycloak/keycloak/releases/tag/26.7.0, consulté le 28/09/2026.
  3. Keycloak Releases (versionnement, cadence, compatibilité, support), dépôt keycloak/keycloak, branche main, https://github.com/keycloak/keycloak/blob/main/RELEASES.md, consulté le 28/09/2026.
  4. Server Developer Guide (Service Provider Interfaces, Authentication SPI, Event Listener SPI, User Storage SPI), sources au tag 26.7.4, https://github.com/keycloak/keycloak/tree/26.7.4/docs/documentation/server_development/topics, consulté le 28/09/2026.
  5. Configuring providers, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/server/configuration-provider.adoc, consulté le 28/09/2026.
  6. Running Keycloak in a container, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/server/containers.adoc, consulté le 28/09/2026.
  7. Using custom Keycloak images, Keycloak Operator, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/operator/customizing-keycloak.adoc, consulté le 28/09/2026.
  8. Avoiding downtime with rolling updates, Keycloak Operator, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/operator/rolling-updates.adoc, consulté le 28/09/2026.
  9. Checking if rolling updates are possible, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/server/update-compatibility.adoc, consulté le 28/09/2026.
  10. Keycloak Operator installation, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/operator/installation.adoc, consulté le 28/09/2026.
  11. Advanced configuration, Keycloak Operator, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/operator/advanced-configuration.adoc, consulté le 28/09/2026.
  12. Upgrading Guide, notes de migration 24.0.0 et 26.3.0 à 26.7.0, sources au tag 26.7.4, https://github.com/keycloak/keycloak/tree/26.7.4/docs/documentation/upgrading/topics/changes, consulté le 28/09/2026.
  13. Server Administration Guide (flux conditionnels, organisations, workflows, mappers de protocole, fédération d'utilisateurs), sources au tag 26.7.4, https://github.com/keycloak/keycloak/tree/26.7.4/docs/documentation/server_admin/topics, consulté le 28/09/2026.
  14. Working with themes et Using the npm UI packages, sources au tag 26.7.4, https://github.com/keycloak/keycloak/tree/26.7.4/docs/guides/ui-customization, consulté le 28/09/2026.
  15. Code source Keycloak 26.7.4 : déclarations des SPI publics et internes, https://github.com/keycloak/keycloak/blob/26.7.4/server-spi/src/main/resources/META-INF/services/org.keycloak.provider.Spi, https://github.com/keycloak/keycloak/blob/26.7.4/server-spi-private/src/main/resources/META-INF/services/org.keycloak.provider.Spi et https://github.com/keycloak/keycloak/blob/26.7.4/model/storage/src/main/java/org/keycloak/storage/UserStorageProviderSpi.java, consulté le 28/09/2026.
  16. Code source Keycloak 26.7.4 : avertissement sur les SPI internes, https://github.com/keycloak/keycloak/blob/26.7.4/quarkus/deployment/src/main/java/org/keycloak/quarkus/deployment/KeycloakProcessor.java et https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/services/ServicesLogger.java, consulté le 28/09/2026.
  17. Code source Keycloak 26.7.4 : statut des fonctionnalités, https://github.com/keycloak/keycloak/blob/26.7.4/common/src/main/java/org/keycloak/common/Profile.java, consulté le 28/09/2026.
  18. Code source Keycloak 26.7.4 : événements et transactions, https://github.com/keycloak/keycloak/blob/26.7.4/server-spi-private/src/main/java/org/keycloak/events/EventListenerProvider.java, https://github.com/keycloak/keycloak/blob/26.7.4/server-spi-private/src/main/java/org/keycloak/events/EventBuilder.java et https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/services/DefaultKeycloakTransactionManager.java, consulté le 28/09/2026.
  19. Code source Keycloak 26.7.4 : providers absents, https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/authentication/DefaultAuthenticationFlow.java, https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/protocol/ProtocolMapperUtils.java et https://github.com/keycloak/keycloak/blob/26.7.4/model/storage/src/main/java/org/keycloak/storage/AbstractStorageManager.java, consulté le 28/09/2026.
  20. Code source Keycloak 26.7.4 : mappers de protocole et politiques de cache, https://github.com/keycloak/keycloak/blob/26.7.4/server-spi-private/src/main/java/org/keycloak/protocol/ProtocolMapper.java, https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/protocol/oidc/mappers/AbstractOIDCProtocolMapper.java et https://github.com/keycloak/keycloak/blob/26.7.4/model/storage/src/main/java/org/keycloak/storage/CacheableStorageProviderModel.java, consulté le 28/09/2026.
  21. Keycloak Test Framework, documentation au tag 26.7.4, https://github.com/keycloak/keycloak/tree/26.7.4/test-framework/docs, consulté le 28/09/2026.
  22. Deprecating Arquillian Testsuite, Keycloak Test Framework Full Support, blog Keycloak du 25/02/2026, source du site keycloak.org, https://github.com/keycloak/keycloak-web/blob/main/blog/2026/deprecating-arquillian-and-keycloak-test-framework-support.adoc, consulté le 28/09/2026.
  23. Configuring logging, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/server/logging.adoc, consulté le 28/09/2026.
  24. Configuring the Management Interface et Gaining insights with metrics, sources au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/server/management-interface.adoc et https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/observability/configuration-metrics.adoc, consulté le 28/09/2026.
  25. Monitoring user activities with event metrics, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/observability/event-metrics.adoc, consulté le 28/09/2026.
  26. Root cause analysis with tracing, source au tag 26.7.4, et interface TracingProvider, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/observability/tracing.adoc et https://github.com/keycloak/keycloak/blob/26.7.4/server-spi-private/src/main/java/org/keycloak/tracing/TracingProvider.java, consulté le 28/09/2026.
  27. Configuring outgoing HTTP requests, source au tag 26.7.4, https://github.com/keycloak/keycloak/blob/26.7.4/docs/guides/server/outgoinghttp.adoc, consulté le 28/09/2026.
  28. Keycloak Extensions, page et fiches du catalogue, source du site keycloak.org, https://github.com/keycloak/keycloak-web/blob/main/pages/extensions.ftl et https://github.com/keycloak/keycloak-web/tree/main/extensions, consulté le 28/09/2026.
  29. keycloak-protocol-cas, README, LICENSE et pom.xml au tag 26.7.4, jacekkow, https://github.com/jacekkow/keycloak-protocol-cas/tree/26.7.4, consulté le 28/09/2026.
  30. Release Keycloak CAS Protocol 26.7.4 et pull request n° 204, jacekkow, https://github.com/jacekkow/keycloak-protocol-cas/releases/tag/26.7.4 et https://github.com/jacekkow/keycloak-protocol-cas/pull/204, consulté le 28/09/2026.
  31. Code source Keycloak 26.7.4 : ordre des post-traitements de jeton, https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/protocol/oidc/token/TokenInterceptorSpi.java et https://github.com/keycloak/keycloak/blob/26.7.4/services/src/main/java/org/keycloak/protocol/oidc/TokenManager.java, consulté le 29/09/2026.

Parlons de votre contexte.

Cet article expose une pratique générale ; votre situation a ses propres contraintes. Décrivez-la, nous répondons avec un périmètre.

Ouvrir le formulaire