[email protected]

Keycloak 26.8 Upgrade: Checklist for Breaking Changes and CVE Fixes

Keycloak 26.8 Upgrade: Checklist for Breaking Changes and CVE Fixes

Editorial note: The information in this article was compiled to the best of our knowledge at the time of publication. Technical details, prices, versions, licensing terms, and external content may change. Please verify the information provided independently, particularly before making business-critical or security-related decisions. This article does not replace individual professional, legal, or tax advice.

Keycloak upgrade with a fallback plan? WZ-IT checks your configuration against the changes in 26.8, tests the upgrade on a copy and operates Keycloak on an ongoing basis if required, see Keycloak at WZ-IT. Book a meeting

Update of 10 November 2026: Keycloak 26.8.2 has been the current version since 5 November 2026. The two patch releases 26.8.1 and 26.8.2 contain further security fixes (33 entries in 26.8.2) and breaking changes, see the section Patch releases 26.8.1 and 26.8.2.

Keycloak 26.8.0 was released on 1 October 2026. The release contains three Keycloak CVE fixes and updated dependencies, promotes SCIM, client secret rotation and multi-cluster v2 to supported status and introduces token exchange delegation for AI agents as a preview. More important for operations are the changes in the upgrading guide: several breaking changes affect identity provider mappers, group claims in authorization policies, logout through brokers and the Admin API.

This article summarizes the changes as a checklist, sorts them by their impact on existing installations and describes the procedure for a minor upgrade. The technical information is based on the Keycloak release notes and upgrading guide, as of 10 November 2026 (26.8.0 to 26.8.2). Recommendations, sequencing and the section on our approach are our own assessments.

Table of Contents

  1. Keycloak 26.8.0 at a glance
  2. Security fixes in 26.8.0
  3. Patch releases 26.8.1 and 26.8.2: CVE fixes and breaking changes
  4. Breaking changes to check before upgrading
  5. Changed behaviour after the upgrade
  6. Organizations: identity providers for multiple organizations
  7. Deprecations and the end of the Realm Operator
  8. New features with supported and preview status
  9. Upgrade procedure step by step
  10. Our approach at WZ-IT
  11. Further guides

Keycloak 26.8.0 at a glance

Attribute Value
Version 26.8.0
Release date 1 October 2026 (release announcement, GitHub)
Previous version 26.7.5 from 30 September 2026 (GitHub)
Current patch version (as of 10 November 2026) 26.8.2 from 5 November 2026 (announcement, GitHub)
Quarkus 3.40 (in 26.7.0: 3.33)
Security fixes 3 Keycloak CVEs plus dependencies
Upgrade type from 26.7 Minor upgrade, no rolling update
Newly supported SCIM API, client secret rotation, multi-cluster v2 (stateless)
Newly preview Token exchange delegation, OID4VCI, parameterized scopes, Client Admin API v2

Important for planning: since 26.6.0, Keycloak supports rolling updates only for patch releases within the same minor version. According to the upgrading guide, moving from 26.7.x to 26.8.0 requires shutting down all nodes. In the standard operating mode, authentication flows in progress are lost, and users have to restart them.

Security fixes in 26.8.0

The release notes list the following security fixes:

CVE Area Issue GitHub
CVE-2026-12388 Identity brokering Administrators with manage-identity-providers could grant administrative roles through IdP mappers and escalate their privileges #50444
CVE-2026-14781 OIDC broker With trustEmail=true and the userinfo endpoint enabled, email_verified from the ID token was applied to a different email from userinfo #50618
CVE-2026-19608 Authorization Services Name-only group claims let same-name groups elsewhere in the hierarchy satisfy group policies #51865
CVE-2026-54515, CVE-2026-59889 Dependency jackson-databind #52168
CVE-2026-59903 Dependency netty-codec-http #52169

The three Keycloak CVEs carry the priority "important" on GitHub. They are not listed in the release notes of 26.7.5. 26.7.5 fixes other vulnerabilities, including CVE-2026-93999 (disabled clients in the token audience) and CVE-2026-89298 (client secret exposed to view-clients via client registration). Teams staying on 26.7 should install 26.7.5; according to GitHub, no further 26.7 versions with the fixes of the 26.8 series had been released by 10 November 2026. In addition, the release notes list 84 entries marked as "Weaknesses", including hardening in SCIM, OID4VCI and the Admin API.

Patch releases 26.8.1 and 26.8.2: CVE fixes and breaking changes

Two patch releases followed 26.8.0. Both contain security fixes and breaking changes. The upgrading guide states that Keycloak introduces breaking changes in minor and patch releases only to fix bugs. The figures come from the release notes and the guide (as of 10 November 2026):

Version Released Entries under "Security fixes" Breaking changes Notable changes
26.8.1 13 October 2026 22, of which 19 with a CVE identifier in the title 6 4
26.8.2 5 November 2026 33, each with its own CVE identifier 14 5

In 26.8.1, two of the 22 entries are collective entries for dependencies (jackson-databind, simple-git) and one describes a flaky test listed under this heading. The announcements give no severity ratings. A selection of entries from 26.8.2, identifiers and short descriptions based on the titles of the Keycloak issues:

CVE Subject Issue
CVE-2026-117691 SAML broker with redirect binding: signature check bypass through a percent-encoded parameter name, login as any user #54714
CVE-2026-103112 Account takeover through a race condition during authentication #54706
CVE-2026-112208 Account takeover through a stale SSO_AUTH note in the identity-first login of organizations #54688
CVE-2026-97175 Automatic account linking through an unverified IdP email address #54707
CVE-2026-107889 Stored XSS on the login page through a kcSanitize bypass #53813
CVE-2026-110931 Terminating the JVM without authentication with a single request through the SAML 1.1 parser (according to the title, an incomplete fix of CVE-2026-7307) #54693
CVE-2026-110932 Persistent disk exhaustion without authentication through the theme gzip cache (according to the title, Keycloak up to and including 26.8.0) #54689
CVE-2026-97847 A client manager can replace the principal of a sessionless token and take over the realm #54697

The complete lists are in the release notes of 26.8.1 and 26.8.2. No 26.7 version exists on GitHub after 26.7.5, neither as a release nor as a tag. The release notes contain no complete list of affected versions; individual entries name versions in their title (issue 54688: reproduced on 26.8.1; issue 54689: up to and including 26.8.0). Whether an older version is affected has to be checked per CVE in the issue.

Breaking changes in 26.8.2. The following selection comes from the section Migrating to 26.8.2 of the upgrading guide (source text: changes-26_8_2.adoc):

Change Who is affected What to do
The Admin REST API checks the audience Custom clients and service accounts that obtain tokens for the Admin REST API Assign the client scope kc-admin-api as a default or optional scope (an optional scope has to be requested when obtaining the token), otherwise 401 (the token needs audience and scope); admin-cli and security-admin-console receive it automatically
Protocol mapper management restricted to realm administrators Delegated client administrators who manage mappers through the Admin REST API Grant permission to manage the realm or list allowed mapper types under "Allowed protocol mapper types for client administrators"; an empty list is the default and blocks mapper management
Dynamic Client Registration: mapper types, default roles, full scope (default roles and full scope: CVE-2026-109081) Users of Dynamic Client Registration Allow mapper types in the client registration policy and in the realm option; the policy Default Roles Disabled is new, Full Scope Disabled now also applies to authenticated registration (it already existed for anonymous registration); forbidden changes return 403; rolling upgrade not supported
SAML broker: bearer confirmation required, ProxyRestriction rejected Setups with an upstream SAML identity provider The upstream must issue a bearer SubjectConfirmation with SubjectConfirmationData; for ProxyRestriction, review the switch "Reject proxy restriction" per identity provider
The SAML adapter validates the issuer Adapters with entityID "idp" or a value that differs from the realm URL Set entityID to the realm URL and download the configuration again in the Admin Console
SAML back-channel logout via SessionIndex SAML clients without "Client signature required" Enable the signature requirement and sign LogoutRequests, or use front-channel logout
Auto-linking requires a trusted email address (CVE-2026-97175) Identity providers whose email address is not treated as verified (such as SAML or custom providers without an email_verified claim) Enable "Trust Email" only if the provider actually verifies email addresses
Organizations: email verification before domain-based membership Organizations with domains and linked identity providers Test SMTP before the upgrade, review the Trust Email setting, review existing memberships (they are not re-evaluated)
Token exchange: exp of access and ID tokens capped by the subject token Clients using standard token exchange Plan for the behaviour (refresh tokens are controlled by a separate switch); enable "Allow exchange token expiration after subject token expiration" only if needed, the guide recommends keeping it off
CIBA: reserved parameter names CIBA clients using names such as sub, iss, aud as form parameters Rename the parameters, otherwise invalid_request
SAML SOAP endpoints limited Users of the SOAP bindings Requests are limited to 120000 bytes by default; adjust with the option spi-login-protocol--saml--max-soap-message-request-size

Among the notable changes for 26.8.2, the guide lists that parsing of SAML 1.1 is disabled by default and that the admin-permissions client is treated as an internal client with fine-grained admin permissions V2 (changes to it return 403).

Breaking changes in 26.8.1. According to Migrating to 26.8.1: with "Enable StartTLS" on, email delivery fails if the SMTP server does not offer STARTTLS, instead of falling back to plaintext (CVE-2026-107121). Backchannel logout tokens from OIDC identity providers are always validated for their signature, even with "Validate Signatures" off, so a JWKS URL or public key has to be configured (CVE-2026-18569). Anyone who changes a field through the API that determines where the client secret is sent (such as tokenUrl or clientId) while sending back the masked secret value receives 400 Bad Request; the actual clientSecret has to be sent, which does not apply to secrets given as a vault expression (CVE-2026-15943). Three changes to the X.509 authenticators follow: key usage validation, CRL files only from the conf directory and a limit of 10 MB for CRL and OCSP responses. Among the notable changes, the guide lists that the semicolon is no longer a query parameter delimiter and that "Skip OTP for Header" in the Conditional OTP authenticator requires a trusted proxy.

No rolling update to 26.8.2. For the move to 26.8.2 there is an exception to the rule that patch releases can be applied as rolling updates. The migration of the client registration policies installs a policy provider that earlier 26.8.x nodes do not know. The guide states: "A rolling upgrade is therefore not supported for this change; shut down the cluster and upgrade all nodes together (or use a recreate update)". In addition, old nodes without the audience mapper issue admin tokens without the required audience, which upgraded nodes reject with a 401.

Breaking changes to check before upgrading

According to Keycloak, breaking changes in minor releases are only introduced to fix bugs. In 26.8.0 there are six items that can directly affect existing configurations (upgrading guide, breaking changes):

Change Who is affected What to do
IdP mappers no longer grant admin roles by default (CVE-2026-12388) Realms where mappers assign admin roles or groups carrying admin roles Enable "Allow granting admin roles via mappers" per identity provider (requires manage-realm), review existing assignments
Client secret only with manage-clients Delegated admins or automation reading secrets with view-clients Grant manage-clients or the equivalent FGAP permission
initiating_idp logout parameter is ignored Setups that suppress upstream logout at the broker Switch to OIDC back-channel or front-channel logout; the transitional option allow-initiating-idp-logout-param is already deprecated
X509 user authentication requires CA Subject DN Realms with X509 login for users Configure the trusted CA per authenticator; enforced from the next major release
Disabled clients no longer in aud and resource_access Resource servers checking these entries Review client status and audience checks
Normalized resource URIs in Authorization Services Policies that distinguish by matrix parameters, dot segments, trailing slash or query Review resource and policy configuration

CVE-2026-19608 also belongs in this review, even though the guide lists it under "Notable changes": bare group names in token claims now resolve to top-level groups only. If you use the "Group Membership" mapper with "Full group path" disabled and your policies target nested groups, you must enable "Full group path", otherwise those policies no longer match (upgrading guide).

Changed behaviour after the upgrade

These changes alter behaviour, load or logs; some require preparation, such as the label on Operator secrets or a dedicated cluster name for stateless:

Change Impact
Login failures stored in the database (login-failures:v2) Brute force lockouts survive restarts; more database connections and database CPU load possible; deployments with the features multi-site or clusterless keep storing the data in the external Infinispan, login-failures:v1 is deprecated but still selectable
Refresh token expiration Capped by the session idle timeout; offline refresh tokens always carry an exp claim
Email verification Emails count as verified only after a completed verification, no longer via account linking by email or admin emails without Verify Email; Trust Email for IdPs and LDAP is unaffected
Client secret rotation and SCIM API Enabled by default; explicit feature flags are no longer needed
Stateless feature No longer enabled by --features=preview, but explicitly as the feature stateless (for example --features=stateless); requires a cluster name other than ISPN
Index creation With more than 300,000 rows in OFFLINE_USER_SESSION (default threshold, configurable), an index is skipped during migration and created in the background afterwards (PostgreSQL, Oracle, MySQL/MariaDB, certain SQL Server editions; only on databases with non-blocking index creation, with the migration strategy manual or validate the SQL statement is only logged)
Introspection act.sub Contains the user ID instead of the username; username in act.preferred_username
NO_PROXY Entries with a leading dot or a space after a comma are now parsed correctly
kcadm and kcreg Set configuration files to 0600 whenever credentials are written
Operator: OIDC client CRs Referenced secrets need the label operator.keycloak.org/kind=KeycloakOIDCClient

The index item matters for installations with large session tables: on PostgreSQL, Keycloak uses CREATE INDEX CONCURRENTLY and detects invalid indexes left by earlier failures (upgrading guide). For MySQL and MariaDB in stateless mode, Keycloak sets the isolation level to READ COMMITTED; if binary logging is enabled with binlog_format = STATEMENT, write operations then fail. Supported database versions are listed in the database guide; for PostgreSQL these are 14 to 18. If you still run PostgreSQL 14, include its end of support in your planning.

Organizations: identity providers for multiple organizations

In 26.8 an identity provider can be linked to multiple organizations; the relationship has changed from many-to-one to many-to-many (release announcement). Migration runs automatically but changes the data model:

  • Existing links are migrated with auto-membership and the Managed type; new links default to Unmanaged.
  • Domain routing moves from the identity provider to the domain. The previous exclusion list no longer exists; excluded domains are migrated without an assigned identity provider.
  • Settings such as "Hide on login page when organization is not resolved" now live in the identity provider settings at realm level.
  • The Admin REST API replaces the organizationId field in IdentityProviderRepresentation with organization links. Scripts and Terraform modules that set this field must be updated.
  • Mappers targeting organization groups store the organization ID explicitly; with multiple organizations, a separate mapper per organization is needed.

After the upgrade, check the "Domains" and "Identity providers" tabs of every organization. If you use organizations for multi-tenant applications, also verify that realm imports set the link policies correctly; issue #53166 fixes a case in which a realm import reset them to permissive defaults.

Deprecations and the end of the Realm Operator

None of these features is removed in 26.8, but they are planned for removal in future releases (upgrading guide, deprecated features):

Deprecated Successor or recommendation
Multi-cluster v1 (--features=multi-site) Multi-cluster v2 with --features=stateless, migration guide
clusterless feature (experimental) stateless
In-memory login failures (login-failures:v1) Default login-failures:v2 in the database
Volatile sessions (persistent-user-sessions disabled) Persistent sessions become the only mode
"Full scope allowed" switch on clients Explicit role scope mappings; Keycloak logs a warning per client at token issuance
Client registration providers default, install, saml2-entity-descriptor Admin REST API or OIDC dynamic client registration
Several switches in "OpenID Connect Compatibility Modes" (list in the guide) Update client applications
Refresh tokens for the client credentials grant Send a new client credentials request
Kerberos credential delegation Deprecated for security reasons, to be removed in a future release
Route in the AUTH_SESSION_ID cookie for sticky sessions Even load distribution without sticky sessions

The Keycloak Realm Operator has reached end of life, and its repository will be archived. Its KeycloakRealm and KeycloakClient resources are superseded by KeycloakRealmImport as well as KeycloakOIDCClient and KeycloakSAMLClient, available as a preview (Managing Keycloak Clients). According to the documentation, KeycloakRealmImport only creates new realms and does not update or delete existing ones.

On the "Full scope allowed" warning: it is suppressed for the built-in clients security-admin-console and admin-cli. The guide describes manual disabling there as unnecessary and points out that it can break Admin Console login.

New features with supported and preview status

Feature Status in 26.8 Context
SCIM API supported, enabled by default Manage users and groups through the SCIM standard, for example for provisioning from other identity systems
Client secret rotation supported, enabled by default Up to two concurrently valid secrets via client policies, coordinated rotation (consumers have to adopt the new secret in time)
Multi-cluster v2 (stateless) supported, disabled by default Multiple clusters without an external Infinispan, sessions in the database; new guide for bare metal and VMs
Token exchange delegation preview Users delegate through consent with the scope delegation:client:<client-id>; token with act claim; authorization only through FGAP V2
Encrypted PEM keys for TLS new Option --https-certificate-key-file-password
Stable node names new --cache-embedded-node-name, set to the pod name automatically by the Operator
Vert.x HTTP client experimental --features=http-client:v2

According to the release announcement, token exchange delegation targets AI agents and automation that act on behalf of a user without receiving admin privileges. A token issued through client delegation grants no Admin API access, even if the client holds service account credentials. If you are already testing the feature from 26.7, change the scope for delegation to a user from delegation to delegation:user (client delegation uses delegation:client) and create the permission through FGAP V2 (token exchange documentation). How to limit agent permissions in general is covered in the article on AI agent permissions and approvals.

Upgrade procedure step by step

The following procedure follows the upgrading guide and adds the checks for 26.8:

Preparation

  1. Determine the current version and read all "Migrating to" sections between that version and the target version, currently 26.8.2 (that is, including 26.8.0, 26.8.1 and 26.8.2). When skipping several minor versions, the changes add up.
  2. Review IdP mappers for assignments of administrative roles or groups carrying admin roles.
  3. Review "Group Membership" protocol mappers and group policies for names without a path.
  4. Identify automation and delegated admins that read client secrets with view-clients.
  5. Review logout flows using initiating_idp and X509 authenticators for users.
  6. Check custom login themes for overrides of social-providers.ftl and CSS for IdP icons.
  7. Rebuild and test custom providers and extensions against Quarkus 3.40; with multiple persistence units in one persistence.xml, note the rename to <default>, and for a unit without its own entities that should load META-INF/orm.xml, the explicit mapping-file declaration.
  8. Review startup parameters: --features=preview no longer enables stateless, and stateless requires --cache-embedded-cluster-name.
  9. For Operator installations: label secrets for KeycloakOIDCClient and replace any dependency on the Realm Operator.
  10. Identify custom clients and service accounts for the Admin REST API and assign them the client scope kc-admin-api (from 26.8.2).
  11. Review the SAML broker, SAML adapter, SAML back-channel logout, Dynamic Client Registration, organizations with domains and SMTP with StartTLS against the breaking changes from 26.8.1 and 26.8.2.

Execution

  1. Test the upgrade on a copy with production data, including logins through every identity provider.
  2. Schedule a maintenance window and stop all nodes of the old version. According to the guide, no rolling update is intended for the move from 26.8.0 or 26.8.1 to 26.8.2 either.
  3. Back up the installation (configuration, themes, providers) and the database. Rolling back is only possible by restoring both backups, as Keycloak does not roll back schema changes.
  4. Deploy the new version, carry over providers/ and themes/, copy conf/ except cache-ispn.xml; reapply custom cache changes based on the new cache-ispn.xml.
  5. Start the first node and follow the schema migration in the log, then start the remaining nodes.

After the upgrade

  1. Organizations: check domains and identity provider links.
  2. Test logins, logout through brokers, token contents (aud, groups, resource_access) and group policies.
  3. Check the log for deprecation warnings, especially "Full scope allowed", and keep a list of affected clients.
  4. Monitor database load, since login failures are now stored in the database by default; wait for background index creation to finish.
  5. Update client libraries (Admin Client, Authorization Client) separately; they are released independently of the server.

For installations using Keycloak as identity provider for VPN or remote access, also test the connected services, for example with NetBird with Authentik or Keycloak.

Our approach at WZ-IT

  1. Inventory. Version, deployment type (VM, container, Kubernetes with the Operator), database, realms, identity providers, themes and custom providers.
  2. Review against the changes. Checking the configuration against all breaking changes and deprecations between your version and 26.8, as a documented list of actions.
  3. Test run. Upgrade on a copy with production data, tests of logins, token contents and connected applications.
  4. Execution. Backup of installation and database, upgrade in an agreed maintenance window, checks after startup and a defined fallback path.
  5. Operations. Monitoring, backups, updates and evaluation of security advisories, optionally through CVE monitoring. Support, consulting and implementation by WZ-IT.

Details on hosting, installation and operations are on the Keycloak at WZ-IT page.

Further guides

Rolling out Keycloak 26.8 without risking logins? We check your realms against the breaking changes, test on a copy and carry out the upgrade with a fallback plan. Book a meeting

Sources

Timo Wevelsiep

Written by

Timo Wevelsiep

Co-Founder & CEO

Co-Founder of WZ-IT. Specialized in cloud infrastructure, open-source platforms and managed services for SMEs and enterprise clients worldwide.

Frequently Asked Questions

Answers to important questions about this topic

Customers from mid-sized business, industry and the public sector, in Germany and internationally

  • Stadtwerke Brühl
  • DGHO e.V.
  • solarwerkstatt berlin
  • Krüger Dirndl
  • ABCO Water Systems
  • Golem.de
  • EVADXB
  • nextGYM
  • AInergy
  • ml&s
  • Odiseo Solutions
  • Annota
  • ARGE
  • SweetConnect GmbH
  • Aphy AG
  • CORGOS
  • Rekorder
  • SolidProof
  • Yonju
  • Keymate
  • Paritel
  • Mr. Clipart
  • Millenium
  • Negosh
  • Führerscheinmacher
  • BTI
  • Deutsche Gesellschaft für Datenschutz
Read client reviews

Enquiry

Plan and carry out your Keycloak upgrade to 26.8

We check your realms, identity providers, themes and extensions against the changes in 26.8, test the upgrade on a copy and carry it out with a fallback plan.

  • You speak directly with Timo and Robin, who are technically responsible
  • A professional assessment of your situation
  • Concrete next steps for infrastructure, software or AI

The conversation is free and non-binding.

WZ-IT's advice on our Azure migration was technically sound and completely non-binding right from the intro call - we took away a great deal.
Jakob ÖschlbergerInno7 GmbH
Timo and Robin, founders of WZ-IT

What is your situation?

WZ-IT's advice on our Azure migration was technically sound and completely non-binding right from the intro call - we took away a great deal.
Jakob ÖschlbergerInno7 GmbH