Keycloak 26 minor upgrades to 26.8

The supported path from Keycloak 26 to 26.8 is to move through each minor release in order, reading the upgrade notes for every release you pass along the way. Teams that are several minor releases behind should not treat 26.8 as a single jump. Each release can change database schema handling, defaults or configuration, and the upgrading guide is the authority for what applies at each step. Since Keycloak 26.0, the project has planned four minor releases a year and has said that breaking changes in a minor release will be opt-in. A skipped minor release therefore means skipped notes, and skipped notes are where upgrades usually fail. The current patch release, 26.8.1, follows the same habit of reading its notes before applying it.

Because breaking changes in a minor release are opt-in, a minor upgrade can install new binaries while existing behavior stays active until you enable the new setting. Check each release's notes for the configuration option that activates each change, and record which options you turned on and when. This lets security and platform owners adopt a change on their own schedule, for example after testing a custom provider or a federated identity flow in a non-production realm. Some items in the 26.8 notes are enforced by the release itself, so opt-in does not cover every change. Confirm in the guide for your starting version which items you can defer and which apply on upgrade regardless of configuration.

If you run Keycloak with the Keycloak Operator on Kubernetes, the Operator documentation strongly recommends manual approval mode for operator updates, to avoid unintended automatic upgrades. In practice, each operator update is reviewed against the release notes for every minor release it crosses before it reconciles the cluster. Put that approval step in your change calendar, and make sure the people who read the notes are the people who approve the change. Automatic approval would let the cluster move through several minor releases without a reviewer present for any of them, which removes the control that opt-in changes are designed to give you.

Do not build your step list from this page. Ask your internal team or implementation partner to derive the exact per-release sequence from the upgrading guide for your starting version. The list should name each release, the notes that apply to it, the database migration mode for that step (automatic at startup by default, or manual SQL, which the guide suggests for large deployments), and a rollback point before each change. Rehearse each step against a copy of production data before starting the next one. Treat the upgrading guide as the document you check against, and treat any summary, including this one, as a pointer to it.

Before you upgrade a Keycloak 26 deployment to 26.8, decide how the database schema will change. By default, Keycloak migrates its schema automatically at startup, so the first upgraded node applies the changes before it begins serving requests. The upgrading guide suggests a different route for large deployments: manual migration, where administrators apply the schema SQL themselves before or during the rollout. Confirm which path your environment will follow and record it in the change plan, because the choice affects who runs the change, when it runs and what happens if it stops partway.

Automatic migration is the simpler option. Keycloak performs the work as part of its normal startup, so no separate database step is needed and the procedure matches the rest of the rolling update. The trade-off is timing and visibility. The migration runs inside the startup of the first node you upgrade, which means the duration of the schema change sits on the critical path of that node, and the database team sees the changes only as they happen. If the migration is slow or fails, the first node may not come up, and you will be troubleshooting under time pressure.

Manual migration gives the database team control. They can review the SQL that Keycloak generates for your database engine, schedule it in a maintenance window, run it against a replica or a restored copy first, and apply it with the change controls your organization already uses for schema work. The cost is additional coordination. Someone must produce the scripts for the exact target version, the rollout must be sequenced so that nodes running 26.8 and nodes running the earlier release can share the database during the transition, and the runbook must state who signs off on the schema change.

High availability changes the test plan. The supported Keycloak high availability designs need a synchronously replicated database, so the migration has to be rehearsed on the same replication topology you run in production, not on a single instance. Check how your replication setup handles long-running DDL, lock waits and failover during the change, and confirm that a failover in the middle of a migration leaves the schema in a state Keycloak can recover from. Your database vendor and the Keycloak high availability documentation are the references for these checks.

Confirm migration duration on a copy of your own data. No reliable figure applies across deployments, because the time depends on database engine, version, table sizes, event and session history, and any custom changes. Restore a recent backup into a staging environment with the same engine and replication design, run the 26.8 migration there, and time it, including the manual SQL path if you plan to use it. Use the measured result to set the maintenance window, decide between automatic and manual migration, and include a tested rollback or restore procedure in the plan.

Agree the test plan before the maintenance window opens, and run it against a staging copy of production built from a recent database backup and the same realm configuration. The plan should cover every path that users and applications depend on, not only the admin console login that most teams check first. List each OIDC and SAML client, each brokered identity provider, each LDAP or Active Directory federation link, and each authentication flow that uses passkeys or OTP. For each item, record the expected result, the test account used, and the person who signs off. A test that passes on a fresh realm with a dummy user tells you little about the mappers and bindings your production realms carry, so use accounts that exist in those realms.

Sign-in tests should follow the paths your applications actually use, with the exact client settings in place. For OIDC and SAML clients, complete a full sign-in and confirm the token or assertion claims that each application reads, since a changed claim can break an application while login still appears to succeed. For brokered identity providers, test first-login account linking and an existing-user login, because those paths behave differently. For LDAP and Active Directory federation, sign in as a user whose group membership changed recently and run a synchronization, to confirm that the directory connection and mappers still work. Include passkey registration, passkey login, OTP enrollment, OTP login and recovery code use, because some users hold one of these as their only second factor.

Three of the 26.8 changes need explicit checks. Back-channel logout tokens from external providers must now have their signatures validated, so confirm that each external provider signs its logout tokens with a key Keycloak can verify, and test a logout initiated by that provider from end to end. Outbound email must use StartTLS with no plaintext fallback, so send a test message through each realm's SMTP settings and confirm that the mail server accepts the connection under that rule, including password reset and verification messages. Finally, open the admin console and the Administration REST API through the separate hostname or context path your reverse proxy exposes, and confirm that the public frontend hostname does not serve them. Check the upgrade notes for the exact behavior of each change and record each result in the sign-off document.

Rollback works differently before and after the database schema changes. Configuration can usually be reverted from the realm exports and settings you captured before the upgrade, and the server binaries or container image can be returned to the prior 26.x release. Once Keycloak has migrated the schema, however, the earlier release should not be expected to run against that database, so returning to the prior version depends on restoring the database backup taken before the window. Anything written after that backup, including new users, sessions, sign-in events and realm changes, is lost unless your team replays it. Confirm your migration mode before the window: with automatic migration, the schema changes when the first upgraded node starts, while manual migration lets your team apply the SQL as a deliberate step with its own checkpoint.

Agree the rollback decision criteria in writing before the window opens, and name the person who makes the call. Useful criteria include which failed tests block progress and which can be tolerated briefly, such as a single connector with a known workaround; how long the team will investigate a fault before choosing rollback, set in advance so the limit is not negotiated during an incident; whether a rollback point still exists, meaning the backup is verified and the migration step has not yet been crossed; and who informs users and application owners. Verify the backup by restoring it to a separate environment before the window, because an unrestorable backup removes the rollback option entirely. Write the criteria into the change record so that the decision follows a checklist the team agreed to earlier.