Why Keycloak upgrades deserve respect
Your Keycloak runs, logins work, and still something nags at you: keycloak.org lists a newer version than the one in your cluster, the release notes list deprecations, and nobody on the team wants to be the one who touches the login system. We get it. But postponing does not make Keycloak upgrades smaller — it makes them bigger. This article turns the dreaded jump into a plannable process.
First, the bare numbers as of September 28, 2026: the current version is 26.7.4, released on September 16, 2026. Feature releases ship on a quarterly rhythm: 26.4.0 on September 30, 2025, 26.5.0 on January 6, 2026, 26.6.0 on April 8, 2026, 26.7.0 on July 9, 2026. In between, patch releases arrive every two to three weeks: 26.7.1 through 26.7.4 appeared within six weeks.
More decisive than the cadence is the support logic: according to the project's security policy, security fixes appear in the current major.minor version or, depending on severity, only in the following release; older versions receive no backports. The community project has no long-term support branch; for that, Keycloak points to the commercial Red Hat build. In plain terms: your version's maintenance window ends with the next feature release, after roughly one quarter.
Don't let the version numbering fool you: since version 26 from October 2024, the big jumps carry numbers like 26.6 or 26.7. They are called minor releases, but they bring new features and deprecations just as the major versions 24 and 25 did before them. So treat every 26.x release like a major upgrade: read the migration changes, test, then roll out.
Still evaluating? What Keycloak does in principle and which identity services it replaces is covered in our overview What is Keycloak?. This article is about the time after that decision: the upgrade as an operational routine.
The typical breaking points
Where do Keycloak upgrades break in practice? From our projects we know three recurring patterns. None of them is a monster, and all three are manageable with preparation — but only if you know where to look.
Custom themes and custom SPIs
The login theme is the most frequent breaking point: customized login screens extend the FreeMarker templates of a specific version. If a release changes the structure or variables of those base templates, your login renders wrong or not at all. The official upgrade guide lists themes as their own migration step: templates, messages, and styles need checking on every jump.
Custom server extensions (SPIs) are trickier still: some of them hook into interfaces that count as internal. If your provider no longer compiles against the new version, you notice early. If only the behavior changes, you notice it in testing — or, worst case, in production. Rule of thumb: the more custom provider code, the bigger the review duty per release.
The database migration only runs one way
By default, Keycloak migrates the database schema automatically on the first start of the new version; alternatively, you generate the SQL migration plan manually for review. That is convenient, but it has one consequence: the migration only runs forward. An older Keycloak version cannot work with the migrated schema, and a downgrade is not supported.
From that follows the first iron rule: no upgrade without a fresh, verified database backup. Not as a formality, but as the only dependable way back.
Deprecations: announced, then removed for good
Keycloak cleans house rigorously — good for the project, work for you. The biggest cut was the switch of the server base from WildFly to Quarkus with version 17 in February 2022: a new configuration world that affected every deployment. Later, the project's own Java adapters were hit; the Node.js adapter is now marked as deprecated on the downloads page.
The pattern is reliable: a feature gets marked as deprecated, runs with a warning for one or two releases, then disappears. If you follow every version, you do small pieces of homework. If you let three releases pile up, you get them all at once — under time pressure.
The plannable upgrade process
The difference between dread and routine is a repeatable process. Ours consists of four building blocks and follows the order of the official Upgrading Guide: first read the migration changes of the target version, then update the server, and finally the connected clients and adapters.
The migration changes are more than a formality: the guide maintains a dedicated chapter per version with every behavior change, new default, and removed option. Twenty minutes of reading per release spare you debugging in live operations. If you are catching up on several versions, read the chapters of every skipped release — in order.
Staging with real data
A staging system with three test users proves nothing. It only becomes meaningful with a real copy: bring over the realm configuration via export, set up the database as an anonymized copy of production, deploy the same themes and SPIs. Then run through the upgrade exactly as it will later run in production.
One thing matters here: run the automatic schema migration against a production-sized dataset, because its duration determines your maintenance window. Afterwards, test what users actually do: login, logout, password reset, token refresh, and the critical flows of every connected application.
Export/import as a safety net
In addition to the database backup, we export all realms via the built-in export feature before every jump. The export belongs in the Git repository, versioned: a diff after the test upgrade shows in black and white what the migration changed in your configuration. And in an emergency, a single realm can be restored without rolling back the entire database.
The rollback path
The rollback is defined up front, not improvised in an emergency. Because the schema migration only runs forward, the path is always the same: a database snapshot taken right before the migration, plus the old container image kept at hand. Add a defined observation window after the rollout (around 30 to 60 minutes) in which you roll back on anomalies; after that, the rule is: fix forward.
And because a rollback that was never rehearsed is no rollback at all: the restore test belongs in the staging phase, not in the night of the emergency.
Blue-green and rolling updates
For patch releases within the same release stream, Keycloak supports rolling updates without downtime: the update-compatibility command checks up front whether the old and new versions may run side by side. For feature releases such as the jump from 26.6 to 26.7, the safe route remains a blue-green approach: bring up the new environment, run smoke tests, switch traffic, keep the old environment standing as a fallback.
In all honesty: the shared database remains the bottleneck. Once the new version has migrated the schema, the old environment is only useful as a fallback together with the database snapshot. What a setup looks like in which switches like these are everyday operations is the subject of our article Keycloak self-hosting.
When deferred upgrades become a security risk
Now to the heart of the matter: why is letting it sit not an option? The CVE logic works against you. When a vulnerability is reported, the fix appears in the current version — and with its publication, the vulnerability is publicly documented, including which older versions are affected. From that moment on, your old version is a described attack target.
The real problem is the pressure to act: if your cluster is two or three feature releases behind, you cannot apply the fix in isolation, because it only exists in the current stream. The deferred routine upgrade turns into an emergency upgrade: all the accumulated deprecations, theme and SPI adjustments at once, while the vulnerability stands open.
On the topic of EOL, it gets concrete fast: older versions move into Keycloak's release archive without comment. If you still run a 24 or 25 today, you are on a version that has not received a single patch since October 2024: two years of documented vulnerabilities. A version like that should not be updated in place but treated as a migration project of its own.
With an identity system, this weighs double: Keycloak manages access to every connected application. A compromised identity layer does not compromise one application but all of them at once. Our mnemonic: a deferred upgrade is not a saved upgrade — it is an unplanned one that picks its own timing.
Rules of thumb for the upgrade budget
First, some framing: the following ranges are our estimate from client projects, not official numbers from the Keycloak project. They depend almost entirely on the degree of customization in your installation, hardly at all on the number of users.
| Starting point | Effort per feature release (our estimate) |
|---|---|
| Standard setup without customizations | 0.5–1 person-day |
| Custom login theme | 1–2 person-days |
| Custom SPIs (own providers) | 2–5 person-days |
| Several releases piled up (a year or more) | 1–3 weeks as its own project |
Why the spread? The standard case is, at its core, a container swap plus testing. Themes and SPIs, by contrast, demand code changes, review, and a second test run. The accumulated backlog is so expensive because you have to work through the migration changes of several versions one after another, each with its own deprecations.
The most important budget decision is not a sum but a rhythm: plan a fixed upgrade window per quarter, in the same rhythm in which releases appear. Four small, plannable efforts per year beat one large, unplannable one — in the end, the quarterly rhythm is the cheapest insurance against the emergency scenario from the previous section.
What running Keycloak costs in total, meaning setup, hosting, and maintenance added up, is broken down in What does Keycloak cost?.
Next steps
If your Keycloak is more than one release behind, start with an inventory: which version is running, which themes and SPIs exist, which migration changes lie between you and 26.7.4? That list becomes a plan with a staging test, a rollback path, and a maintenance window — and the plan becomes a routine.
We take on upgrades like these as a clearly scoped project or as part of ongoing operations, embedded in our custom software development work. If you want to know how far your setup is from the quarterly rhythm: Book a free intro call — in 30 minutes we clarify your version status, the risks, and the next sensible jump.
