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
Keycloak 26.8.0 was released on 1 October 2026. The release contains three security fixes, 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. All information is based on the Keycloak release notes and upgrading guide, as of October 2026.
Table of Contents
- Keycloak 26.8.0 at a glance
- Security fixes in 26.8.0
- 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) |
| 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. 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 and watch for backports of the 26.8 fixes. In addition, the release notes list more than 80 hardening items marked as "Weaknesses", mainly in SCIM, OID4VCI and the Admin API.
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 (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 do not break configurations but alter behaviour, load or logs:
| Change | Impact |
|---|---|
| Login failures stored in the database (login-failures:v2) | Brute force lockouts survive restarts; more database connections and database CPU load possible |
| 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, only by --features=stateless; requires a cluster name other than ISPN |
| Index creation | With more than 300,000 rows in OFFLINE_USER_SESSION, an index is skipped during migration and created in the background afterwards (PostgreSQL, Oracle, MySQL/MariaDB, certain SQL Server editions) |
| 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; 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 |
| Switches in "OpenID Connect Compatibility Modes" | Update client applications |
| Refresh tokens for the client credentials grant | Send a new client credentials request |
| Kerberos credential delegation | Removed for security reasons |
| 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).
On the "Full scope allowed" warning: it is suppressed for the built-in clients security-admin-console and admin-cli. The guide explicitly advises against disabling the switch manually for them, as this 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, rotation without downtime |
| 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 from delegation to delegation:user 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 26.8.0. 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>. - 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.
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.
- 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; 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, Upgrading Guide (Migrating to 26.8.0)
- GitHub, Keycloak release 26.8.0
- 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
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.
Frequently Asked Questions
Answers to important questions about this topic
Keycloak 26.8.0 was released on 1 October 2026, as a blog post on keycloak.org and as a release on GitHub. The previous version, 26.7.5, was released on 30 September 2026.
The release notes list three Keycloak CVEs: CVE-2026-12388 (identity provider mappers could grant administrative roles), CVE-2026-14781 (the OIDC broker applied email_verified from the ID token to a different email address returned by the userinfo endpoint) and CVE-2026-19608 (name-only group claims let same-name groups elsewhere in the hierarchy satisfy group policies). Updated dependencies (jackson-databind, netty-codec-http) are included as well.
The three CVEs are not listed in the 26.7.5 release notes (as of 1 October 2026). 26.7.5 contains its own security fixes, including CVE-2026-93999 on disabled clients in the token audience. For CVE-2026-19608 the GitHub issue carries backport labels for 26.6 and 26.7, but no patch release with this fix had been published at the time of writing.
No. Keycloak supports zero-downtime rolling updates only for patch releases within the same minor version. Moving from 26.7 to 26.8 is a minor upgrade: all nodes running the old version are stopped, then the new version migrates the database schema. Rolling back is only possible by restoring a database backup.
No. The new allowAdminRoleMapping setting is false after the upgrade and blocks future assignments of administrative roles through mappers. Roles and group memberships granted earlier remain in place and must be removed manually if required.
No. Multi-cluster v1 (the multi-site feature with an external Infinispan) is deprecated and is planned for removal in a future major release. Its successor is multi-cluster v2 with the stateless feature, which reached supported status in 26.8 and stores session data in the database.
It has preview status in 26.8, not supported. Delegation is authorized exclusively through Fine-Grained Admin Permissions V2, the scope is now called delegation:user instead of delegation, and tokens carry an act claim identifying the acting client. Production agent scenarios should take the preview status into account.
No. Keycloak deliberately suppresses the new deprecation warning for these two built-in clients. Disabling the switch manually can break Admin Console login immediately. For your own clients, the upgrading guide recommends disabling Full Scope Allowed and assigning roles explicitly through scope mappings.
Not necessarily. The identity provider button section on the login page has been redesigned. Themes that override social-providers.ftl or use CSS targeting the identity provider icons may render incorrectly and should be tested before the production upgrade.
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.
LinkedInLet's Talk About Your Idea
Whether a specific IT challenge or just an idea - we look forward to the exchange. In a brief conversation, we'll evaluate together if and how your project fits with WZ-IT.
Arrange a callback
Companies worldwide trust WZ-IT
