Marshalling is the process of converting Java objects into bytes to send them across the network between {project_name} servers.
With {project_name} 26, the marshalling library has changed from JBoss Marshalling to Infinispan Protostream.
The libraries are not compatible between each other and, it requires some steps to ensure the session data is not lost.
WARNING: JBoss Marshalling and Infinispan Protostream are not compatible with each other and incorrect usage may lead to data loss.
Consequently, all caches are cleared when upgrading to this version.
To prevent losing user sessions upgrade to Keycloak 25 first and enable the persistent sessions feature as outlined in the migration guide for {project_name} 25.
= Operator no longer defaults to proxy=passthrough
The Operator will no longer default to the hostname v1 setting of proxy=passthrough. This allows deployments using hostname v2 for a fixed edge hostname to work as desired without additional options.
Keycloak Pods will now have default affinities to prevent multiple instances from the same CR from being deployed on the same node, and all Pods from the same CR will prefer to be in the same zone to prevent stretch cache clusters.
= Operator's default CPU and memory limits/requests
In order to follow the best practices, the default CPU and memory limits/requests for the Operator were introduced. It affects both non-OLM and OLM installs. To override the default values for the OLM install, edit the `resources` section in the operator's https://github.com/operator-framework/operator-lifecycle-manager/blob/master/doc/design/subscription-config.md#resources[subscription].
= Consistent usage of UTF-8 charset for URL encoding
`org.keycloak.common.util.Encode` now always uses the `UTF-8` charset for URL encoding instead relying implicitly on the `file.encoding` system property.
In this release, the LDAP connection pool configuration relies solely on system properties. The main
reason is that the LDAP connection pool configuration is a JVM-level configuration rather than specific to an individual
realm or LDAP provider instance.
Compared to previous releases, any realm configuration related to the LDAP connection pool will be ignored.
If you are migrating from previous versions where any of the following settings are set to your LDAP provider(s), consider using system properties instead:
* `connectionPoolingAuthentication`
* `connectionPoolingInitSize`
* `connectionPoolingMaxSize`
* `connectionPoolingPrefSize`
* `connectionPoolingTimeout`
* `connectionPoolingProtocol`
* `connectionPoolingDebug`
For more details, see link:{adminguide_link}#_ldap_connection_pool[Configuring the connection pool].
= Persisting revoked access tokens across restarts
In this release, revoked access tokens are written to the database and reloaded when the cluster is restarted by default when using the embedded caches.
To disable this behavior, use the SPI option `spi-single-use-object-infinispan-persist-revoked-tokens` as outlined in the https://www.keycloak.org/server/all-provider-config[All provider configuration] {section}.
The SPI behavior of `SingleUseObjectProvider` has changed that for revoked tokens only the methods `put` and `contains` must be used.
This is enforced by default, and can be disabled using the SPI option `spi-single-use-object-infinispan-persist-revoked-tokens`.
. Review your current cache configurations in the external {jdgserver_name} and update them with those outlined in the latest version of the {project_name}'s documentation.
. While previous LoadBalancer configurations will continue to work with {project_name}, consider upgrading
an existing Route53 configurations to avoid prolonged failover times due to client side DNS caching.
= Deprecating remote-store in embedded Infinispan caches
In {project_name} versions 24 to 25 to achieve a multi-site setup, a remote store in embedded Infinispan caches was configured.
Manual configurations for the cache XML for multi-site were discouraged as CLI options to configure the caches are available.
With the upgraded multi-site feature in 26, the same CLI options exist, but don't use embedded Infinispan caches anymore.
In the community, remote stores for embedded Infinispan caches were used in some setups to keep user sessions when the {project_name} cluster was shut down or upgraded.
This was never supported, documented or tested.
As a fully supported alternative, the persistent user sessions feature should be used instead.
Due to this, using remote caches in embedded Infinispan caches is now marked as deprecated with the plan to remove it.
As it was never used outside multi-site setups that now achieve this by different means, it might be removed even in a future minor release.
To be able to use the deprecated feature, you need to enable the feature `remote-store-cross-dc` or {project_name} will not start.
There is an experimental feature `remote-cache` which allows leveraging the new multi-site mechanisms to store session related data in an external {jdgserver_name} server also for single site setups.
It used to be difficult to regain access to a {project_name} instance when all admin users were locked out. The process required multiple advanced steps, including direct database access and manual changes. In an effort to improve the user experience, {project_name} now provides multiple ways to bootstrap a new admin account, which can be used to recover from such situations.
Consequently, the environment variables `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` have been deprecated. You should use `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` instead. These are also general options, so they may be specified via the cli or other config sources, for example `--bootstrap-admin-username=admin`. For more information, see the new https://www.keycloak.org/server/bootstrap-admin-recovery[Bootstrap admin and recovery] guide.
= Application Initiated Required Action redirect now contains kc_action Parameter
The required action provider name is now returned via the `kc_action` parameter when redirecting back from an application initiated required action execution.
This eases the detection of which required action was executed for a client. The outcome of the execution can be determined via the `kc_action_status` parameter.
Note: This feature required changes to the Keycloak JS adapter, therefore it is recommended to upgrade to the latest version of the adapter if you want to make use of this feature.
The CLI command `kc.[sh|bat] import` now has placeholder replacement enabled. Previously placeholder replacement was only enabled for realm import at startup.
The `RealmProvider` Java API now contains a new method `Stream<RealmModel> getRealmsStream(String search)` which allows searching for a realm by name.
While there is a default implementation which filters the stream after loading it from the provider, implementations are encouraged to provide this with more efficient implementation.
{project_name} now determines the format of the keystore and trust store based on the file extension. If the file extension is `.p12`, `.pkcs12` or `.pfx`, the format is PKCS12. If the file extension is `.jks`, `.keystore` or `.truststore`, the format is JKS. If the file extension is `.pem`, `.crt` or `.key`, the format is PEM.
You can still override automatic detection by specifying the `https-key-store-type` and `https-trust-store-type` explicitly. The same applies to the management interface and its `https-management-key-store-type`. Restrictions for the FIPS strict mode stay unchanged.
NOTE: The `+spi-truststore-file-*+` options and the truststore related options `+https-trust-store-*+` are deprecated, we strongly recommend to use System Truststore. For more details refer to the relevant https://www.keycloak.org/server/keycloak-truststore[guide].
= Improving performance for selection of identity providers
New indexes were added to the `IDENTITY_PROVIDER` table to improve the performance of queries that fetch the IDPs associated with an organization, and fetch IDPs that are available for login (those that are `enabled`, not `link_only`, not marked as `hide_on_login`).
If the table currently contains more than 300.000 entries,
{project_name} will skip the creation of the indexes by default during the automatic schema migration, and will instead log the SQL statements
on the console during migration. In this case, the statements must be run manually in the DB after {project_name}'s startup.
Also, the `kc.org` and `hideOnLoginPage` configuration attributes were migrated to the identity provider itself, to allow for more efficient queries when searching for providers. As such, API clients should use the `getOrganizationId/setOrganizationId` and `isHideOnLogin/setHideOnLogin` methods in the `IdentityProviderRepresentation`, and avoid setting these properties using the legacy config attributes that are now deprecated.
Some of the paths for the `common` resources of the `keycloak` theme have changed, specifically the resources for third-party libraries. Make sure to update your custom themes accordingly:
- `node_modules/patternfly/dist` is now `vendor/patternfly-v3`
- `node_modules/@patternfly/patternfly` is now `vendor/patternfly-v4`
- `node_modules/@patternfly-v5/patternfly` is now `vendor/patternfly-v5`
- `node_modules/rfc4648/lib` is now `vendor/rfc4648`
Additionally, the following resources have been removed from the `common` theme:
- `node_modules/alpinejs`
- `node_modules/jquery`
If you previously used any of the removed resources in your theme, make sure to add them to your own theme resources instead.
{project_name} by default does not use XA datasources. However, this is considered unsafe if more than one datasource is used.
Starting with this release, you need to use XA datasources if you are adding additional datasources to {project_name}.
If the default datasource supports XA, you can do this by setting the `--transaction-xa-enabled=true` option. For additional datasources, you need to use
the `quarkus.datasource.<your-datasource-name>.jdbc.transactions=xa` option in your `quarkus.properties` file.
At most one datasource can be non-XA.
Recovery isn't supported when you don't have persistent storage for the transaction store.
The deprecated hostname v1 feature was removed. This feature was deprecated in {project_name} 25 and replaced by hostname v2. If you are still using this feature, you must migrate to hostname v2. For more details, see the https://www.keycloak.org/server/hostname[Configuring the hostname (v2)] and https://www.keycloak.org/docs/latest/upgrading/#new-hostname-options[the initial migration guide].
= Proxy option removed
The deprecated `proxy` option was removed. This option was deprecated in {project_name} 24 and replaced by the `proxy-headers` option in combination with hostname options as needed. For more details, see https://www.keycloak.org/server/reverseproxy[using a reverse proxy] and https://www.keycloak.org/docs/latest/upgrading/index.html#deprecated-proxy-option[the initial upgrading guide].
Since the database is now the source of truth for user sessions, it is possible to restrict the size of the session caches to reduce memory usage.
If you use the default `conf/cache-ispn.xml` file the caches for storing user and client sessions are by default configured to store only 10000 sessions and one owner for each entry.
Update your custom embedded Infinispan cache configuration file with configuration similar to one shown below for caches `sessions`, `clientSessions`, `offlineSessions`, and `offlineClientSessions`:
[,xml]
----
<distributed-cache name="sessions" owners="1">
<!-- other configuration -->
<memory max-count="10000"/>
</distributed-cache>
----
For more details proceed to the https://www.keycloak.org/server/caching[Configuring distributed caches] guide.
= Support for legacy `redirect_uri` parameter and SPI options has been removed
Previous versions of {project_name} had supported automatic logout of the user and redirecting to the application by opening logout endpoint URL such as
`http(s)://example-host/auth/realms/my-realm-name/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri`. This functionality was deprecated in {project_name} 18 and has been removed in this version in favor of following the OpenID Connect specification.
As part of this change the following related configuration options for the SPI have been removed:
If you were still making use these options or the `redirect_uri` parameter for logout you should implement the link:https://openid.net/specs/openid-connect-rpinitiated-1_0.html[OpenID Connect RP-Initiated Logout specification] instead.
There are now generalized events for updating (`UPDATE_CREDENTIAL`) and removing (`REMOVE_CREDENTIAL`) a credential. The credential type is described in the `credential_type` attribute of the events.
The new event types are supported by the Email Event Listener.
The following event types are now deprecated and will be removed in a future version: `UPDATE_PASSWORD`, `UPDATE_PASSWORD_ERROR`, `UPDATE_TOTP`, `UPDATE_TOTP_ERROR`, `REMOVE_TOTP`, `REMOVE_TOTP_ERROR`
