Keycloak 25 to 26 upgrade

The session strategy has to be settled before the version change because it determines whether users stay signed in while the upgrade runs. Keycloak keeps user and client sessions that record who is signed in and which tokens have been issued. If those sessions live only in memory or in a distributed cache, every node restart removes the sessions held on that node. A version change adds risk, because cached data written by the old release may not be read cleanly by the new one. Without a change to session storage, users could be asked to sign in again across every application that relies on Keycloak, at the moment your teams are watching the upgrade most closely. Moving sessions into the database first means a node restart no longer depends on what happens to be in the cache.

Persistent sessions have a cost in the database. Each session is written to and read from the database, so write volume and table growth rise with login volume and session lifetime. Before enabling the setting, read the upgrading guide for your target release and confirm three things: the exact name of the persistent session setting and whether it is a feature flag or a configuration option, which database tables it touches, and how expired sessions are cleaned up. Ask your database administrator to estimate the write load at your busiest login hour and to size storage for the session tables. Confirm that your production database engine and version appear on the supported list for the release you are moving to, because the upgrading guide governs what is supported. Take a verified backup before the change so that you can reverse it if the load is higher than expected.

The Protostream cache change is the second reason to review sessions first. Protostream is the serialization format Keycloak uses to encode objects stored in its distributed caches. When that encoding changes, cache contents written under one release may need to be discarded or rebuilt when nodes move to the next one. During a rolling update, nodes on different versions can also disagree about what they read from the same cache. Treat the cache configuration as an item to review line by line. List every cache customized in your current deployment, identify any custom providers that store objects in a cache, and read the upgrading guide's instructions for clearing, migrating or rebuilding cache data for your target release. Record the decision for each cache so that the change board can see what was reviewed and why.

Test the behavior in staging before production. Build a staging environment from a copy of your production configuration, including the same number of nodes, the same database engine and the same proxy path. Sign in with several test users, keep sessions open in each connected application, and then restart each node one at a time while the others continue serving requests. After every restart, confirm that existing sessions still validate, that token refresh succeeds and that logout reaches the applications. Repeat the test after the cache configuration and session settings are in place. Record every session that is lost, the node and step where it happened and the log messages from that point. Do not schedule the production change until each lost session has a documented cause and an accepted fix. Your identity team owns this sign-off, and DeployOpen can run the test as part of a fixed-scope engagement if you want an outside check.

Hostname and proxy configuration is one of the most common reasons a Keycloak upgrade passes in a test environment and then breaks in production. When the server builds URLs from the wrong host, scheme or port, users land on broken redirects, relying applications reject tokens because the issuer does not match what they expect, and administrators cannot reach the admin console. These failures often appear only after the server runs behind the real load balancer and reverse proxy, so this check belongs before cutover and should be planned as its own work item.

Start from the production guidance in the Keycloak documentation. It calls for TLS on all communication, a reverse proxy with path restrictions, and the admin console and Administration REST API served on a different hostname or context path from public frontend URLs. Before you change anything, write down the decisions these requirements force: the public hostname users and applications see, the separate hostname or path for administration, which paths the proxy forwards to the internet, and where TLS terminates and whether traffic is re-encrypted before it reaches Keycloak. Record how the current 25 deployment answers each question so you can see what the upgrade changes.

Then verify the outputs that break first. Fetch the OpenID Connect discovery document for a test realm and confirm that the issuer and endpoint URLs use the public hostname and scheme that clients expect. Compare the issuer claim in a freshly issued token with the value each relying application has configured. Check that every registered redirect URI matches the URL the server generates, including port and path. Confirm that the admin console and Administration REST API respond from the management network and are refused from the public internet, and that the metrics and health endpoints are not reachable from public addresses.

The exact hostname v2 and proxy-header settings for your target release must be confirmed in the Keycloak 26 documentation for that release, not copied from a 25 configuration file. Work through those settings in a staging environment that matches production: the same proxy chain, certificates, DNS names and forwarded headers. Record the issuer values and redirect behavior before and after the change, and repeat the admin access tests from both networks. Ask any implementation partner to state in the written scope which staging environment, proxy configuration and test cases they will use to sign off this step.

Every custom authenticator, event listener, user storage provider, theme and protocol mapper must be rebuilt against the Keycloak 26 API and retested on the target release before you cut over. These components are compiled against Keycloak's internal interfaces, so a build that succeeded on 25 can still fail at startup, be silently skipped, or behave differently at runtime. Inventory every custom artifact, record which Keycloak version each one was built for, and rebuild them from source against the release you plan to run. Deploy them to a staging instance that uses a copy of your production realm configuration and a restored copy of the database, so the test reflects the data your users actually have.

Build the test matrix around the flows your users depend on. For each client type, cover browser-based confidential web applications, public single-page applications using PKCE, native and mobile clients, and service accounts that use client credentials. For each, sign in with a standard user, a user with custom attributes, and a user who needs a second factor or passkey. Add brokered logins through every upstream OIDC, SAML and social provider you have configured, and run LDAP or Active Directory sync in both full and changed-user modes, checking group and role mappers and any custom user storage behavior. Confirm the token claims in ID and access tokens match a baseline captured from the current 25 deployment for the same test accounts, paying particular attention to custom protocol mappers.

Logout and messaging need their own cases because they touch external systems. Test front-channel logout from the browser and backchannel logout from each relying party, and confirm that sessions end in every application that should end them. Send a password reset, an account verification and an admin notification through SMTP and check delivery, headers and the TLS negotiation with your relay. Finally, exercise admin actions in the console and through the Administration REST API, including realm changes, client creation, user disablement and any custom admin extensions. Write down the expected result for each case before the run, so a failure is a clear defect rather than a judgment call.

The 26.8 changes can break flows that worked before. Keycloak now enforces StartTLS for SMTP without plaintext fallback, so a mail relay that offered only unencrypted delivery or presented an unexpected certificate will fail email silently for some users. Mandatory signature validation of backchannel logout tokens from external providers can reject logout requests that were previously accepted without verification, leaving sessions open in relying parties. Login failures are also persisted to the database by default, which changes database load and may affect any custom event listener that assumed otherwise. These behaviors must be tested on the exact target version, because a check that passed on an earlier 26.x release does not prove the later one behaves the same way.

Before the upgrade window, confirm which 26.x release you will run and freeze it for the test cycle. Ask your partner or internal team to deliver the test plan, the expected results for each case, and the list of custom artifacts covered, and make sure the quote states who executes the matrix and who signs off the results. Keep the staging hostname, proxy headers and TLS configuration identical to production, since a mismatch there can hide or create the same failures. Treat any failed case as a blocker for cutover until its cause is understood and either fixed or formally accepted by the service owner.