●Change8

Migrating to Keycloak 26.3.3

Version 26.3.3 introduces 2 breaking changes. This guide details how to update your code.

Released: 8/20/2025

2
Breaking Changes
1
Migration Steps
21
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

user-profile registration pageoidc backchannel logout tokencore email sendingcore lightweight access tokendist/quarkus `--optimized` flaginfinispan JDBC_PINGinfinispan JDBC_PING2caching docs securing-cache-communicationdocs configuration generationdist/quarkus tracing spansdist/quarkus Maven surefire plugindocs ExternalLinksldap import/syncoidc certs endpointadmin/api SMTP connection testcaching docdist/quarkus provider defaultcore Jakarta Mailldap memberOf attribute/certificates/jwt.credential/generate-and-downloadlogin/ui Credentials label uniqueness

Breaking Changes

●Issue #1

Breaking template change: Unknown `locale` input field added to user-profile registration page. This may affect custom themes or templates related to user profile registration.

●Issue #2

Backwards incompatible changes to 26.3.0 cause NullPointerException when requesting /certificates/jwt.credential/generate-and-download. Review usage of the JWT credential generation endpoint.

Migration Steps

  1. 1
    Before upgrading refer to https://www.keycloak.org/docs/latest/upgrading/#migration-changes for a complete list of changes.

Release Summary

This release focuses on stability, upgrading core dependencies like Quarkus and Infinispan, and resolving numerous bugs across LDAP synchronization, OIDC flows, cluster stability, and documentation errors. Several template and API backward incompatibilities were introduced or fixed.

Need More Details?

View the full release notes and all changes for Keycloak 26.3.3.

View Full Changelog