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
- Keycloak 26.8.0 at a glance
- Security fixes in 26.8.0
- Patch releases 26.8.1 and 26.8.2: CVE fixes and breaking changes
- Breaking changes to check before upgrading
- Changed behaviour after the upgrade
- Organizations: identity providers for multiple organizations
- Deprecations and the end of the Realm Operator
- New features with supported and preview status
- Upgrade procedure step by step
- Our approach at WZ-IT
- 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
- 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.
- Review IdP mappers for assignments of administrative roles or groups carrying admin roles.
- Review "Group Membership" protocol mappers and group policies for names without a path.
- Identify automation and delegated admins that read client secrets with view-clients.
- Review logout flows using initiating_idp and X509 authenticators for users.
- Check custom login themes for overrides of social-providers.ftl and CSS for IdP icons.
- 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. - Review startup parameters: --features=preview no longer enables stateless, and stateless requires --cache-embedded-cluster-name.
- For Operator installations: label secrets for KeycloakOIDCClient and replace any dependency on the Realm Operator.
- Identify custom clients and service accounts for the Admin REST API and assign them the client scope kc-admin-api (from 26.8.2).
- 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
- Test the upgrade on a copy with production data, including logins through every identity provider.
- 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.
- 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.
- 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.
- Start the first node and follow the schema migration in the log, then start the remaining nodes.
After the upgrade
- Organizations: check domains and identity provider links.
- Test logins, logout through brokers, token contents (aud, groups, resource_access) and group policies.
- Check the log for deprecation warnings, especially "Full scope allowed", and keep a list of affected clients.
- Monitor database load, since login failures are now stored in the database by default; wait for background index creation to finish.
- 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
- Inventory. Version, deployment type (VM, container, Kubernetes with the Operator), database, realms, identity providers, themes and custom providers.
- 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.
- Test run. Upgrade on a copy with production data, tests of logins, token contents and connected applications.
- Execution. Backup of installation and database, upgrade in an agreed maintenance window, checks after startup and a defined fallback path.
- 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
- Authentik vs. Zitadel, two open-source identity providers compared, with Keycloak as reference.
- NetBird with Authentik or Keycloak, setting up SSO for a self-hosted VPN.
- PostgreSQL 14 end of life, upgrade paths for the database underneath Keycloak.
- AI agent permissions and approvals, how agents receive only the permissions they need.
- Managed open source, operation of Keycloak and other open-source applications by WZ-IT.
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
- Keycloak, Keycloak 26.8.0 released
- Keycloak, Keycloak 26.8.1 released
- Keycloak, Keycloak 26.8.2 released
- Keycloak, Upgrading Guide (Migrating to 26.8.0)
- GitHub, Keycloak release 26.8.0
- GitHub, Keycloak release 26.8.1
- GitHub, Keycloak release 26.8.2
- GitHub, upgrading guide source 26.8.2 (changes-26_8_2.adoc)
- GitHub, upgrading guide source 26.8.1 (changes-26_8_1.adoc)
- GitHub, Keycloak release 26.7.5
- GitHub issue #50444, CVE-2026-12388
- GitHub issue #50618, CVE-2026-14781
- GitHub issue #51865, CVE-2026-19608
- GitHub issue #53074, CVE-2026-93999
- GitHub issue #50992, redesigned identity provider buttons
- Keycloak, Migrating from multi-cluster v1 to v2
- Keycloak, Token Exchange
- Keycloak, Configuring the database
- Keycloak Operator, Realm Import
- Keycloak Operator, Managing Keycloak Clients
- GitHub, Keycloak Realm Operator













