Ressources
Monter de version Keycloak sans casser la production : politique de support, migration de base et retour arrière
Dernière version de Keycloak, branches supportées et calendrier : monter de version sans casser la production, migration de base et retour arrière.
L'équipe CTN Solutions · publié le , mis à jour le · 25 min de lecture
Faits vérifiés sur les sources primaires le
Keycloak publie une version mineure environ quatre fois par an, et seule la dernière reçoit des correctifs. Selon la politique du projet, une instance restée en 26.7 n'est plus supportée depuis la publication de la 26.8.0, le 1er octobre 2026, au lendemain de la 26.7.5 : cinq correctifs de la branche 26.7 ont été publiés entre le 5 août et le 30 septembre, dont la 26.7.5 qui corrige quatorze vulnérabilités référencées CVE. Monter de version devient une opération de routine. Or chaque montée mineure impose d'arrêter tous les nœuds, migre le schéma de la base sans retour possible, et peut casser une extension, un thème ou l'outil qui pilote la configuration depuis Git.
Faits datés
Keycloak 26.8.0, publiée le 1er octobre 2026 et dernière version disponible au ; Keycloak 27 n'est pas publié. Guide de montée de version au tag 26.8.0, pages officielles et dépôts cités vérifiés le .
Vérifié le
Ce que la politique de support impose réellement
Le projet a formalisé sa politique dans le fichier RELEASES.md de son dépôt : schéma majeure.mineure.correctif, avec une exception assumée (un correctif important de bogue ou de sécurité peut rompre la compatibilité) ; mineures environ quatre fois par an, majeures tous les deux à trois ans, correctifs au besoin. Le fichier attend des utilisateurs qu'ils montent à chaque nouvelle mineure, et leur demande de lire le guide de montée de version et de tester dans un environnement de test avant toute montée, correctif compris.
La politique de sécurité du dépôt, SECURITY.md, ajoute une nuance que les tableaux de fin de vie omettent : selon sa gravité, une vulnérabilité est corrigée dans la mineure courante ou, pour une gravité plus faible ou un simple durcissement, seulement dans la mineure suivante. Rester sur le dernier correctif ne garantit donc pas toutes les corrections. Les avis de sécurité paraissent dans les notes de version et dans les tickets GitHub de type CVE, deux canaux à surveiller en plus du blog.
La branche 26.7 montre ce rythme. La 26.6.0 est sortie le 8 avril 2026, la 26.7.0 le 9 juillet, puis la 26.7.1 le 5 août, la 26.7.2 le 19 août, la 26.7.3 le 31 août, la 26.7.4 le 16 septembre et la 26.7.5 le 30 septembre ; la 26.8.0 a suivi le 1er octobre. Chacun de ces cinq correctifs porte une rubrique « Breaking changes » dans le guide de montée de version :
- 26.7.1 : un rôle d'administration obtenu par un mappeur de protocole ne donne plus accès à l'API d'administration, et l'affectation d'une portée à un client exige la permission
managesur les portées ; - 26.7.2 : l'ancien point de terminaison de liaison de compte initiée par le client est désactivé par défaut ;
- 26.7.3 : une URI de redirection qui contient des paramètres OIDC comme
stateoucodeest refusée par défaut ; - 26.7.4 : les URI de ressources des services d'autorisation sont normalisées avant comparaison ;
- 26.7.5 : la condition de politique client
client-updater-source-groupscompare le chemin complet du groupe, si bien qu'un sous-groupe désigné par son seul nom se réécrit en chemin, et unOrganizationProviderpersonnalisé doit implémentergetByAlias.
Un correctif se lit donc avant d'être déployé. Surtout, la fenêtre de support d'une mineure n'a aucun recouvrement : la 26.7.5 est sortie le 30 septembre 2026, la 26.8.0 le lendemain, et depuis cette publication la 26.7 n'est plus corrigée ; toute durée de montée, répétition comprise, devient une durée d'exposition.
Le Red Hat build of Keycloak, voie documentée du support long
SECURITY.md oriente lui-même les équipes qui ne peuvent pas monter régulièrement vers le Red Hat build of Keycloak, présenté comme offrant un support long de versions précises. La page de cycle de vie de Red Hat en fixe les règles.
| Critère | Keycloak communautaire | Red Hat build of Keycloak |
|---|---|---|
| Rythme des mineures | Environ quatre par an | Environ une tous les six mois, fondée sur les mineures amont paires (27.0, 27.2, 27.4...) |
| Durée de correction d'une mineure | Jusqu'à la mineure suivante | Jusqu'à la deuxième mineure suivante, soit environ douze mois |
| Fin d'une majeure | Six mois de correctifs sur la dernière mineure après la majeure suivante | Au moins six mois de maintenance après la majeure suivante ; à partir de la 27.x, cycle de vie d'au moins trois ans par majeure |
| Version la plus récente au | 26.8.0 | 26.6 (documentation Red Hat) |
| Contrat | Aucun | Souscription Red Hat |
Deux réserves. Le profil produit des sources de la documentation Keycloak indique que l'image conteneur n'est supportée que sur OpenShift, et pas sur les autres distributions Kubernetes : sur EKS, GKE ou AKS, faites confirmer le périmètre de support par Red Hat avant tout choix. Et une mineure maintenue douze mois déplace la contrainte sans la supprimer : il faut toujours une montée par an, avec la même méthode.
Ce qui casse d'une version à l'autre
Le guide de montée de version découpe chaque version en ruptures (« Breaking changes »), changements notables, fonctionnalités dépréciées et fonctionnalités retirées. En mineure ou en correctif, le projet n'introduit de rupture que pour corriger un bogue ; RELEASES.md ajoute que les mineures visent des ruptures activables au choix, et que les garanties ne couvrent que les fonctionnalités supportées et les API publiques, pas les préversions. Le tableau classe les ruptures documentées dans la branche 26 selon la couche touchée.
| Couche | Exemples documentés dans la branche 26 | Où la rupture se voit |
|---|---|---|
| Configuration du serveur | Options SPI au format à double tiret, l'ancien format devenant ambigu (26.3) ; cache-ispn.xml à ne plus recopier mais à reprendre sur le fichier livré (26.3) ; fonctionnalité dynamic-scopes renommée parameterized-scopes (26.7) | Avertissements ou échec au démarrage, cluster qui ne se forme pas |
| Base de données | Colonne REALM_ID ajoutée à OFFLINE_CLIENT_SESSION et remplie pendant la migration (26.6) ; PostgreSQL 13 retiré (26.5) ; colonne LAST_SESSION_REFRESH_COARSE et index d'expiration reconstruits sur OFFLINE_USER_SESSION, table ORG_IDENTITY_PROVIDER créée et colonne ORGANIZATION_ID retirée de IDENTITY_PROVIDER (26.8) | Durée de migration, SQL d'index à appliquer à la main ou index créés en arrière-plan après le démarrage (26.8), refus de démarrer |
| Extensions | Transaction de session démarrable une seule fois, KeycloakContext revu hors requête, point d'extension RefreshTokenProvider (26.7) ; OrganizationProvider#getByAlias sans implémentation par défaut (26.7.5) ; Quarkus 3.40 et unité de persistance JPA par défaut renommée <default> (26.8) ; SPI internes modifiables à chaque mineure | Erreurs à l'exécution, pas forcément à la compilation |
| Thèmes | Réglages FreeMarker 2.3.32 et boutons de connexion revus (26.7) ; thèmes base abstraits (26.6) ; plus de HTML dans les messages de connexion (26.5) ; boutons des fournisseurs d'identité de la page de connexion redessinés, social-providers.ftl compris (26.8) | Pages de connexion, e-mails, console de compte |
| API d'administration | Alias d'un fournisseur d'identité immuable, toute modification renvoyant 400 (26.7) ; rôle view-system supprimé (26.7) ; rôles d'administration par mappeur ignorés (26.7.1) ; secret d'un client masqué pour un appelant limité à view-clients (26.8) ; mappeurs de fournisseur d'identité bloqués pour les rôles d'administration tant que allowAdminRoleMapping n'est pas activé (26.8) | Outil GitOps, scripts, délégation d'administration |
| Protocoles | Authentification X509 d'un client appelée à exiger le DN de l'autorité (26.7) ; paramètres OIDC refusés dans les URI de redirection (26.7.3) ; paramètre initiating_idp ignoré par défaut à la déconnexion (26.8) ; DN de l'autorité exigé dans la console pour l'authentification X509 des utilisateurs (26.8) | Connexion des clients, déconnexion |
| Opérateur | Version v2beta1 des CRD Keycloak et KeycloakRealmImport, v2alpha1 dépréciée ; sous OLM, blocage des opérateurs plus anciens dans le même cluster (26.6) ; Secret référencé par un KeycloakOIDCClient tenu de porter l'étiquette operator.keycloak.org/kind: KeycloakOIDCClient (26.8) | Installation et mise à jour de l'opérateur |
Deux lignes méritent attention. La migration 26.6 de REALM_ID interdit de faire tourner la 26.6 à côté d'une version antérieure pendant ou après la migration ; le guide cite un essai du projet sur PostgreSQL à environ 1 320 secondes pour dix millions de lignes. Les ruptures d'administration de 26.7.1 touchent les délégations construites par des mappeurs : chaque mappeur qui porte un rôle d'administration se relit avant la montée, et le rôle s'affecte directement ou par un groupe. Pour les fédérations, l'exigence X509 et le refus des paramètres OIDC dans les redirections se vérifient client par client.
Le guide n'impose pas de passer par chaque mineure intermédiaire, mais demande de relire les changements de chaque version franchie : passer de 26.5.7 à 26.8.0 revient à lire treize rubriques « Migrating to », dont la rubrique 26.6.5 que le guide de la 26.8.0 a ajoutée. La méthode utile est une table de décision jointe au ticket de montée : chaque ligne du guide y est classée « concerne », « ne concerne pas » ou « à vérifier », avec l'action et son responsable.
Préparer : inventaire, répétition sur une copie de production et outillage GitOps
Inventorier ce qui tourne réellement
La table de décision se rapporte à ce qui est déployé, pas à ce que le dépôt Git décrit. L'inventaire relève la version et le digest de l'image, la configuration effective, les fonctionnalités activées (préversions comprises, dont la montée n'est pas garantie), les JAR du dossier providers, les thèmes personnalisés, la version de l'opérateur et celle du moteur de base.
# Référence synthétique, lecture seule
bin/kc.sh --version # version de Keycloak, JVM, système
bin/kc.sh show-config # configuration effective ; en 26.8, valeurs sensibles et toutes les options SPI masquées
ls /opt/keycloak/providers/ # extensions livrées dans l'image
kubectl -n <ESPACE> get keycloaks.k8s.keycloak.org <NOM> \
-o jsonpath='{.spec.image}{"\n"}{.spec.update}{"\n"}'La version du moteur se confronte à la table des bases supportées de la cible : pour la 26.8.0, notamment PostgreSQL 14.x à 18.x, Aurora PostgreSQL 15.x à 17.x, MySQL 8.0 et 8.4, MariaDB 10.6, 10.11, 11.4 et 11.8. PostgreSQL 13 a été retiré en 26.5 après sa fin de vie ; PostgreSQL 14 atteint la sienne le 12 novembre 2026. Au , aucun guide Keycloak publié n'annonce le retrait de PostgreSQL 14, et la table des bases de la branche principale du dépôt le liste toujours ; une base en 14 doit néanmoins entrer dans le plan de montée, et la table se relit à chaque nouvelle mineure.
Répéter la migration sur une copie de la base de production
Une base de développement vide ne révèle ni la durée de migration ni les index reportés. La répétition se fait sur une copie restaurée de la dernière sauvegarde de production, isolée, avec l'image candidate. Deux précautions : couper les sorties (serveur SMTP, fédérations LDAP en écriture, écouteurs d'événements vers un SIEM) pour ne contacter aucun vrai utilisateur, et appliquer à la copie les contrôles d'accès et la durée de conservation de la production, puisqu'elle contient les mêmes données personnelles.
Au premier démarrage de la nouvelle version, le serveur applique automatiquement les changements de schéma, dans un délai de migration de 30 minutes par défaut. Si une table dépasse 300 000 enregistrements, l'index concerné n'est pas créé pendant la migration de schéma. Depuis la 26.8.0, sur les bases qui savent créer un index sans bloquer lectures et écritures (PostgreSQL, Oracle Enterprise Edition, MySQL et MariaDB, éditions Enterprise, Developer et Azure SQL de Microsoft SQL Server), le serveur crée cet index en arrière-plan après le démarrage. Sur les autres bases, avec les stratégies manual ou validate, ou avec l'option --spi-connections-jpa--quarkus--auto-create-missing-indexes=false, le SQL à appliquer à la main apparaît dans les journaux. La répétition sert à relever l'un ou l'autre ; la 26.8.0 en fournit un cas, puisqu'elle ajoute la colonne LAST_SESSION_REFRESH_COARSE à OFFLINE_USER_SESSION et reconstruit ses index d'expiration. La stratégie manuelle produit le SQL sans l'appliquer, pour qu'un administrateur de base le relise et le planifie.
# Référence synthétique d'après le guide de montée 26.8.0, à adapter
# Produire le SQL de migration au lieu de l'appliquer ; le serveur s'arrête ensuite
bin/kc.sh start --optimized \
--spi-connections-jpa--quarkus--migration-strategy=manual \
--spi-connections-jpa--quarkus--migration-export=<CHEMIN>/keycloak-database-update.sql
# Allonger le délai si la répétition a mesuré une migration plus longue
bin/kc.sh start --optimized --transaction-setup-timeout=<DUREE_MESUREE_AVEC_MARGE>
# Reporter la création d'index plutôt que de bloquer le démarrage (seuil par défaut 300000)
bin/kc.sh start --optimized \
--spi-connections-liquibase--quarkus--index-creation-threshold=<SEUIL>
# 26.8.0 : journaliser le SQL d'index au lieu de créer l'index en arrière-plan
bin/kc.sh start --optimized \
--spi-connections-jpa--quarkus--auto-create-missing-indexes=falseDepuis la 26.7, ce fichier inclut aussi les changements de schéma des extensions qui déclarent leurs propres entités. Après le SQL, le premier démarrage peut encore migrer des données, comme le remplissage de REALM_ID en 26.6 : la durée mesurée couvre le démarrage complet.
La répétition est acquise quand quatre résultats sont consignés : durées de migration et de démarrage, SQL d'index éventuel ou durée de création des index en arrière-plan, parcours de contrôle passés, avertissements de dépréciation émis au démarrage. Ces quatre résultats fixent la fenêtre de la montée réelle, avec sa marge.
Vérifier extensions, thèmes et outillage GitOps
Extensions et thèmes se testent contre la version en production et la version visée, avec une matrice de versions dans l'intégration continue. Pour les thèmes, le guide recommande de comparer chaque gabarit personnalisé au gabarit de base de la nouvelle version.
L'outil qui pilote la configuration depuis Git a son propre calendrier. Au , la dernière publication de keycloak-config-cli, la 6.5.1 du 22 mai 2026, est construite et testée en intégration continue contre Keycloak 26.5.5 au plus ; son README promet de supporter les quatre dernières versions « si possible ». Contre un serveur 26.7 ou 26.8, la combinaison n'est pas validée par le projet. Le fournisseur Terraform du projet Keycloak (dépôt keycloak/terraform-provider-keycloak) supporte officiellement les trois dernières mineures et, depuis sa version 5.10.0 du 5 octobre 2026, mène ses essais d'acceptation de 26.0.8 à 26.8.0.
Dans les deux cas, la répétition rejoue l'application complète de la configuration contre la préproduction migrée, puis vérifie qu'une seconde exécution ne produit aucun écart : l'alias devenu immuable d'un fournisseur d'identité se découvre là, pas en production. Propriété des champs et dérive sont traitées dans « Piloter la configuration Keycloak en GitOps : adoption, dérive et suppression de champs ». Un export de royaume ne remplace pas la sauvegarde : il exclut événements, sessions persistées, état des workflows et jetons révoqués, et sa cohérence n'est garantie que nœuds arrêtés.
Exécuter : mise à jour progressive ou recréation, puis retour arrière
Choisir la stratégie
Depuis la 26.6.0, la mise à jour progressive des correctifs est active par défaut : passer à un correctif plus récent de la même branche majeure.mineure peut se faire sans interruption, sur au moins deux nœuds, un nœud à la fois, en attendant que la sonde de démarrage du nouveau nœud réussisse. Toute montée mineure ou majeure reste une recréation : arrêt de tous les nœuds de l'ancienne version, puis démarrage de la nouvelle.
La commande update-compatibility tranche : elle enregistre des métadonnées avec l'ancienne configuration, puis les compare avec la nouvelle version et ses options exactes. Seul le code de sortie fait foi.
# Référence synthétique : toutes les options de chaque image doivent être passées
bin/kc.sh update-compatibility metadata --file=<CHEMIN>/metadata.json <OPTIONS_ACTUELLES>
# puis, avec la version candidate :
bin/kc.sh update-compatibility check --file=<CHEMIN>/metadata.json <OPTIONS_CANDIDATES>
# 0 progressive possible ; 1 erreur inattendue ; 2 option invalide ;
# 3 recréation nécessaire ; 4 fonctionnalité rolling-updates désactivéeLe code de sortie de update-compatibility décide du mode de montée
Le schéma part du code de sortie de la vérification de compatibilité et montre le mode de montée ou l'erreur qu'il désigne.
Schéma défilable horizontalement ; sa version textuelle complète suit.
Lire le schéma sous forme textuelle
- La commande
update-compatibility checkest lancée avec la version candidate. - Code 0 : mise à jour progressive possible.
- Code 3 : recréation nécessaire.
- Code 4 : fonctionnalité rolling-updates désactivée.
- Code 1 : erreur inattendue.
- Code 2 : option invalide.
Même entre deux correctifs, la recréation s'impose si l'on modifie --cache, --cache-config-file, --cache-stack, --cache-embedded-mtls-enabled, --cache-remote-host ou --cache-remote-port, le moteur, le schéma, le nom, l'hôte ou le port de base, ou une fonctionnalité dont la politique l'exige, comme persistent-user-sessions. Le contenu d'un fichier de cache personnalisé n'est pas vérifié : s'il change, sa compatibilité se teste. Pendant une progressive, le guide recommande l'affinité de session au répartiteur, ne garantit que la connexion, la déconnexion et les opérations des clients OpenID Connect, et prévient qu'un utilisateur des consoles peut devoir recharger la page. Un parcours SAML se vérifie donc en préproduction. La 26.8 déprécie par ailleurs l'ajout de la route du nœud au cookie AUTH_SESSION_ID, que son guide de montée juge sans bénéfice notable depuis la 26.6.
Avec le Keycloak Operator
L'opérateur expose le choix dans spec.update.strategy : RecreateOnImageChange, la valeur par défaut, réduit le StatefulSet à zéro à chaque changement d'image ; Auto lance une tâche Kubernetes qui exécute la vérification de compatibilité, puis choisit ; Explicit laisse décider par le champ revision, obligatoire avec cette stratégie. La documentation met en garde contre Explicit combiné aux mises à jour automatiques de l'opérateur par OLM, qui peuvent provoquer une progressive non supportée.
# Référence synthétique d'après le guide de l'opérateur 26.8.0
apiVersion: k8s.keycloak.org/v2beta1
kind: Keycloak
metadata:
name: <NOM>
spec:
image: <REGISTRE>/keycloak@sha256:<DIGEST_CIBLE>
update:
strategy: Auto# Stratégie retenue par l'opérateur au dernier changement : RecreateUpdateUsed
kubectl -n <ESPACE> get keycloaks.k8s.keycloak.org <NOM> \
-o jsonpath='{range .status.conditions[*]}{.type}={.status} {.message}{"\n"}{end}'
kubectl -n <ESPACE> wait --for=condition=Ready keycloaks.k8s.keycloak.org/<NOM> --timeout=<DUREE>L'opérateur a sa propre montée : avec l'image par défaut, il déploie celle de sa version, et une mise à jour automatique par OLM devient une montée de Keycloak non décidée, sans retour possible. La documentation recommande installPlanApproval: Manual, l'alignement de l'image personnalisée sur la version de l'opérateur, et l'ordre suivant : images des ressources Keycloak d'abord, opérateur ensuite. Un ancien opérateur incompatible avec la nouvelle image est arrêté entre-temps, par exemple en réduisant son Deployment à zéro réplica.
Ce que la recréation fait perdre
Avant une recréation, le guide demande d'arrêter Keycloak, de sauvegarder l'ancienne installation, de traiter les transactions XA ouvertes (suppression de data/transaction-logs/ si elles sont activées) et de sauvegarder la base. L'arrêt vide les caches : connexions en cours, changements et réinitialisations de mot de passe engagés disparaissent, et les utilisateurs concernés recommencent leur parcours. Depuis la 26.8, les compteurs de détection de force brute sont stockés en base par défaut et survivent au redémarrage, sauf si l'ancien mode en mémoire, login-failures:v1, déprécié, a été réactivé ; ceux qu'une version antérieure tenait en mémoire disparaissent encore à l'arrêt qui précède la montée. Les sessions utilisateur survivent parce que persistent-user-sessions est actif par défaut depuis la 26.0 ; si la fonctionnalité a été désactivée, ce que la 26.8 déprécie, seules les sessions hors ligne subsistent.
Retour arrière : la base ne revient pas en arrière seule
Après la montée, le schéma n'est plus compatible avec l'ancien serveur, et Keycloak ne sait pas annuler les changements de base. Revenir en arrière consiste à restaurer l'ancienne installation, puis la base depuis sa sauvegarde ; tout ce qui a été écrit entre-temps disparaît : comptes créés, mots de passe changés, consentements, sessions, modifications d'administration. D'où une règle : fixer à l'avance le point de non-retour, en pratique la réouverture du trafic ; au-delà, un défaut se corrige vers l'avant. Pour un correctif déployé en progressive, le guide ne décrit pas de retour progressif : la voie documentée reste la même.
Retour arrière : l'ordre des opérations
Le schéma suit les trois opérations d'un retour arrière, dans l'ordre décrit par l'article, et ce qu'elles font perdre.
Schéma défilable horizontalement ; sa version textuelle complète suit.
Lire le schéma sous forme textuelle
- Les nœuds de la nouvelle version sont arrêtés.
- L'ancienne installation est restaurée.
- La base est restaurée depuis la sauvegarde prise avant la montée.
- L'ancienne version ne redémarre qu'ensuite.
- Les comptes créés, mots de passe changés, consentements, sessions et modifications d'administration écrits après la montée disparaissent.
# Référence synthétique PostgreSQL : point de restauration logique avant la montée
pg_dump --format=custom --file=keycloak-avant-<VERSION>.dump --dbname='<CONNEXION>'
# Retour arrière : tous les nœuds arrêtés, ancienne installation restaurée, puis la base ; l'ancienne version ne redémarre qu'ensuite
pg_restore --clean --if-exists --single-transaction \
--dbname='<CONNEXION>' keycloak-avant-<VERSION>.dumpSur une base volumineuse, une sauvegarde physique restaurable à un instant donné peut remplacer le vidage logique ; dans tous les cas, la restauration s'éprouve avant la fenêtre, dans un environnement isolé.
Monter de version Keycloak, de la publication au retour arrière
Le parcours d'une montée de version, de la lecture du guide à la décision de réouverture ou de retour arrière.
Schéma défilable horizontalement ; sa version textuelle complète suit.
Lire le schéma sous forme textuelle
- La publication d'une nouvelle version déclenche la lecture du guide de montée pour chaque version franchie.
- La montée est répétée sur une copie de la base de production.
- Si la migration, les extensions, les thèmes ou l'outillage GitOps échouent, l'équipe corrige, puis rejoue la répétition jusqu'à validation.
- Une fois la répétition validée, la base est sauvegardée avec une restauration testée, et l'image précédente est conservée.
- S'il s'agit d'un correctif de la même branche et que la vérification de compatibilité renvoie 0, la mise à jour est progressive, un nœud à la fois ; sinon, tous les nœuds sont arrêtés et la nouvelle version migre la base au démarrage.
- Dans les deux cas, les parcours de contrôle sont exécutés avant la réouverture du trafic.
- S'ils sont conformes, l'opération est consignée et la prochaine montée planifiée ; sinon, l'équipe restaure l'ancienne installation, puis la base.
Liste de contrôle
| Moment | Action | Preuve attendue |
|---|---|---|
| Avant | Inventorier ce qui tourne réellement | Sorties de kc.sh --version et show-config, spec.image, liste des JAR |
| Avant | Classer chaque ligne du guide pour chaque version franchie | Table de décision jointe au ticket |
| Avant | Vérifier le moteur de base | Version dans la plage supportée par la cible |
| Avant | Tester extensions, thèmes et outillage GitOps sur la cible | Suite verte ; seconde application sans écart |
| Avant | Répéter sur une copie de production, sorties coupées | Durées mesurées, SQL d'index relevé ou création en arrière-plan chronométrée, parcours passés |
| Avant | Sauvegarder la base et éprouver la restauration | Restauration réussie en environnement isolé ; digest précédent noté |
| Avant | Fixer fenêtre, critères d'arrêt et point de non-retour | Décision écrite ; aucun autre changement du chemin d'authentification |
| Avant | Opérateur : stratégie explicite, approbation OLM manuelle | spec.update.strategy ; installPlanApproval: Manual |
| Pendant | Décider progressive ou recréation | Code de sortie consigné ; condition RecreateUpdateUsed |
| Pendant | Recréation : arrêter tous les nœuds, traiter les transactions XA | Aucun pod de l'ancienne version actif |
| Pendant | Suivre la migration de schéma | Fin de migration dans les journaux ; SQL d'index appliqué ou planifié, ou index créés en arrière-plan présents en base |
| Pendant | Contrôler démarrage et formation du cluster | /health/ready sur chaque pod ; taille de vue attendue |
| Après | Exécuter les parcours de contrôle avant réouverture | Connexion OIDC et SAML, rafraîchissement, déconnexion, fédération, e-mails |
| Après | Rejouer l'outillage GitOps | Aucun écart, ou écarts expliqués |
| Après | Relever les avertissements de dépréciation au démarrage | Liste reportée au ticket de la montée suivante |
| Après | Consigner versions, durées, écarts | Ticket clos ; montée suivante planifiée |
Pour cadrer cette méthode sur une plateforme existante, voir la page Mise en production Kubernetes : ouvrir par étapes.
Se préparer à Keycloak 27 et tenir une cadence
Ce qui est officiel au
Keycloak 27 n'est ni publié ni daté par une annonce. Les jalons GitHub donnent des échéances indicatives : 27.0 au 31 mars 2027 (jalon de développement au 29 janvier 2027), puis 27.1 à 27.3 entre le 30 juin 2027 et le 6 janvier 2028. Ce sont des dates d'outil de suivi, pas des engagements : le jalon de la 26.8 visait le 30 septembre 2026, et la 26.8.0 a été publiée le 1er octobre.
Le ticket ouvert « Extended release support » (n° 52656) en dit davantage. Ses auteurs écrivent que la 27.0 sortira en 2027, que la 26.x restera supportée environ six mois après, et que la dernière 26.x doit être la 26.8, ainsi supportée environ douze mois au total. Pour la seule branche 27.x, il soumet au vote quatre options : deux mineures supportées avec une cadence de trois mois (environ six mois chacune) ou de six mois (environ douze mois) ; une version sur deux en support long ; ou un support long suivi d'une maintenance étendue limitée aux failles importantes. Les mainteneurs ne retiendront pas forcément l'option la plus votée, et aucune décision n'est publiée au : c'est une proposition, pas une politique.
Ce que les guides 26.x annoncent déjà
Le contenu de la 27 n'est pas publié, mais les guides 26.x annoncent des retraits ; seuls ceux du tableau sont explicitement rattachés à la version 27 ou à « la prochaine majeure ».
| Élément | Annonce du guide | Guide | À faire dès la 26.x |
|---|---|---|---|
| Usages de SHA1 | Tous retirés en version 27 | 26.7.0 | Inventorier algorithmes de signature et de hachage configurés |
Option allow-oidc-params-in-redirect-uris et attribut client allow.oidc.params.in.redirect.uris | Retirés en 27 | 26.7.3 | Corriger les URI de redirection au lieu de réactiver l'ancien comportement |
Champ displayTest de ConsentScopeRepresentation | Retiré en 27.0 | 26.4.0 | Lire displayText dans les clients de l'API de compte |
| DN de l'autorité pour l'authentification X509 d'un client, puis d'un utilisateur | Clients : validé côté serveur à la prochaine majeure, création, mise à jour et import refusés sans lui. Utilisateurs : nouveau comportement imposé à la prochaine majeure, option « Revalidate Client Certificate » dépréciée | 26.7.0 (clients), 26.8.0 (utilisateurs) | Renseigner le DN dans la console et dans les fichiers GitOps, pour les clients comme pour les authentificateurs X509 des utilisateurs |
Client JavaScript d'autorisation : ready et init() | Retirés à la prochaine majeure | 26.1.0 | Supprimer ces appels |
getAll() des API Organizations et OrganizationMembers | Retirés à la prochaine majeure | 26.1.0 | Passer à list(first, max) |
| Attributs de traces des requêtes HTTP | Retirés à la prochaine majeure | 26.6.0 | Adapter les tableaux de bord et requêtes de traces |
D'autres retraits sont annoncés « possiblement » en 27, comme l'option d'audiences multiples pour l'authentification JWT des clients (26.2).
La ligne SHA1 appelle une vérification. Dans le code de la 26.8.0, la politique OTP par défaut utilise l'algorithme HmacSHA1, et la note de dépréciation ne détaille pas les usages concernés. Tant que les notes de la 27.0 ne sont pas publiées, la politique OTP de chaque royaume entre dans l'inventaire, et changer son algorithme en production se teste avec les applications d'authentification réellement utilisées.
D'autres éléments sont dépréciés sans date de retrait, dont les permissions d'administration fines v1, l'échange de jetons v1, les piles de transport autres que jdbc-ping, la version v2alpha1 des CRD Keycloak et KeycloakRealmImport et la base non UTF-8 ; la 26.8 y ajoute notamment la désactivation des sessions persistantes, le stockage en mémoire des échecs de connexion (login-failures:v1), l'interrupteur « Full Scope Allowed » des clients et, pour une majeure future non datée, le multi-cluster v1 (fonctionnalité multi-site) et les fournisseurs d'enregistrement de clients default, install et saml2-entity-descriptor. Le guide 26.4 ajoute qu'une future majeure refusera de démarrer si un fichier de cache redéfinit les caches par défaut sans --cache-config-mutate=true. Une majeure est le moment où le projet s'autorise des retraits non activables au choix : les avertissements de dépréciation relevés à chaque répétition forment la liste de travail.
Une politique de cadence écrite
La politique de support ne laisse aucune marge implicite : la cadence s'écrit, avec des délais fixés par l'équipe selon sa politique de gestion des vulnérabilités. Le tableau relie chaque événement amont au support qu'il laisse.
| Événement amont | Support restant sur la version en place | Action |
|---|---|---|
| Nouveau correctif 26.8.x | La branche 26.8 reste corrigée | Lire la rubrique du guide ; appliquer, en progressive si la vérification renvoie 0 |
| Publication de la 26.8.0, le 1er octobre 2026 | La 26.7 n'est plus corrigée depuis cette publication | Instance en 26.7 : lancer la répétition sans attendre ; monter dans le délai fixé |
| Publication de la 27.0 | La dernière 26.x reçoit six mois de correctifs, selon RELEASES.md | Ouvrir le projet de migration majeure ; répéter sur la 27.0 dès sa sortie |
| Politique 27.x décidée (ticket n° 52656) | Selon l'option retenue | Réviser la cadence interne |
Trois pratiques réduisent le coût de chaque montée : faire tourner la suite de tests des extensions contre les versions nocturnes publiées par le projet, pour voir une rupture avant la sortie ; traiter chaque avertissement de dépréciation comme un ticket, pour que la 27 ne concentre pas toute la dette de la branche 26 ; garder la même procédure pour un correctif et pour une mineure. Si ce rythme est hors de portée, le choix se fait entre le support long de Red Hat et une acceptation de risque documentée, qui nomme la durée d'exposition et les mesures compensatoires.
Sources officielles et limites de lecture
RELEASES.md, ajouté à la branche principale le 16 septembre 2026, figure à l'identique au tag 26.8.0 : c'est un texte récent, susceptible d'évoluer avec la décision sur le ticket n° 52656. Jalons et ticket décrivent des intentions ; seules les notes de la 27.0 feront foi sur son contenu. Le dépôt porte des tags 26.6.5, 26.6.6 et 26.6.7, du 24 juillet au 7 septembre 2026, sans publication GitHub ; le guide de montée de la 26.8.0 leur ajoute une rubrique « Migrating to 26.6.5 », qui reprend la rupture de la 26.7.1 sur les rôles d'administration obtenus par un mappeur de protocole. Ces tags ne permettent pas de conclure à un support de la 26.6, que RELEASES.md ne prévoit pas.
Sources
- Keycloak Releases (versionnement, cadence, compatibilité, support et fin de vie), dépôt keycloak/keycloak, tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/RELEASES.md, consulté le 07/10/2026.
- Security Policy (versions supportées, Red Hat build of Keycloak), dépôt keycloak/keycloak, branche main, https://github.com/keycloak/keycloak/blob/main/SECURITY.md, consulté le 07/10/2026.
- Extended release support, ticket n° 52656, dépôt keycloak/keycloak, https://github.com/keycloak/keycloak/issues/52656, consulté le 07/10/2026.
- Milestones, dépôt keycloak/keycloak, https://github.com/keycloak/keycloak/milestones, consulté le 07/10/2026.
- Releases (26.7.0 à 26.7.5, 26.8.0 et versions antérieures), dépôt keycloak/keycloak, https://github.com/keycloak/keycloak/releases, consulté le 07/10/2026.
- Release 26.7.5 (correctifs de sécurité), dépôt keycloak/keycloak, https://github.com/keycloak/keycloak/releases/tag/26.7.5, consulté le 07/10/2026.
- Release 26.8.0 (notes de version), dépôt keycloak/keycloak, https://github.com/keycloak/keycloak/releases/tag/26.8.0, consulté le 07/10/2026.
- Tag 26.6.7 (tags 26.6.5 à 26.6.7 sans publication), dépôt keycloak/keycloak, https://github.com/keycloak/keycloak/releases/tag/26.6.7, consulté le 07/10/2026.
- Upgrading Guide (préparation, téléchargement, migration de la base, migration des thèmes), sources au tag 26.8.0, https://github.com/keycloak/keycloak/tree/26.8.0/docs/documentation/upgrading/topics, consulté le 07/10/2026.
- Migration Changes 26.0.0 à 26.8.0 (fichiers changes-26_x_y.adoc), dépôt keycloak/keycloak, tag 26.8.0, https://github.com/keycloak/keycloak/tree/26.8.0/docs/documentation/upgrading/topics/changes, consulté le 07/10/2026.
- Checking if rolling updates are possible, source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/server/update-compatibility.adoc, consulté le 07/10/2026.
- Avoiding downtime with rolling updates (Operator), source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/operator/rolling-updates.adoc, consulté le 07/10/2026.
- Keycloak Operator Installation (approbation manuelle OLM, mise à jour de l'opérateur), source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/operator/installation.adoc, consulté le 07/10/2026.
- Using custom Keycloak images (Operator), source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/operator/customizing-keycloak.adoc, consulté le 07/10/2026.
- Configuring the database (bases supportées, stratégies de migration), source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/server/db.adoc, consulté le 07/10/2026.
- Table des bases supportées, gabarit databases.adoc, tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/server/templates/databases.adoc, consulté le 07/10/2026.
- Table des bases supportées, gabarit databases.adoc, branche main, https://github.com/keycloak/keycloak/blob/main/docs/guides/server/templates/databases.adoc, consulté le 07/10/2026.
- Importing and exporting realms, source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/server/importExport.adoc, consulté le 07/10/2026.
- Running Keycloak in a container (profil produit : support de l'image limité à OpenShift), source au tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/docs/guides/server/containers.adoc, consulté le 07/10/2026.
- Profile.java (fonctionnalités rolling-updates, persistent-user-sessions, login-failures et politiques de mise à jour), tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/common/src/main/java/org/keycloak/common/Profile.java, consulté le 07/10/2026.
- UpdateSpec.java (stratégies, champ revision), tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/operator/src/main/java/org/keycloak/operator/crds/v2beta1/deployment/spec/UpdateSpec.java, consulté le 07/10/2026.
- Main.java et ShowConfig.java (option --version et commande show-config), tag 26.8.0, https://github.com/keycloak/keycloak/tree/26.8.0/quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/cli/command, consulté le 07/10/2026.
- OTPPolicy.java (politique OTP par défaut), tag 26.8.0, https://github.com/keycloak/keycloak/blob/26.8.0/server-spi/src/main/java/org/keycloak/models/OTPPolicy.java, consulté le 07/10/2026.
- Red Hat build of Keycloak Life Cycle and Support Policies, Red Hat, https://access.redhat.com/support/policy/updates/red_hat_build_of_keycloak_notes, consulté le 07/10/2026.
- Red Hat build of Keycloak 26.6, documentation produit, Red Hat, https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/26.6, consulté le 07/10/2026.
- keycloak-config-cli (README, CHANGELOG, pom.xml et intégration continue au tag v6.5.1), dépôt adorsys/keycloak-config-cli, https://github.com/adorsys/keycloak-config-cli, consulté le 07/10/2026.
- terraform-provider-keycloak (README, section Supported Versions, version 5.10.0), dépôt keycloak/terraform-provider-keycloak, https://github.com/keycloak/terraform-provider-keycloak, consulté le 07/10/2026.
- Versioning Policy, PostgreSQL Global Development Group, https://www.postgresql.org/support/versioning/, consulté le 07/10/2026.
- pg_dump, documentation PostgreSQL 17, https://www.postgresql.org/docs/17/app-pgdump.html, consulté le 07/10/2026.
- pg_restore, documentation PostgreSQL 17, https://www.postgresql.org/docs/17/app-pgrestore.html, consulté le 07/10/2026.