Release Notes

The execution Verify Existing Account By Email is one of the alternatives that the First Login Flow has to allow a brokering account to be linked to an existing Red Hat build of Keycloak user. This step is executed when the user logs in into Red Hat build of Keycloak through the broker for the first time, and the identity provider account is already present in Red Hat build of Keycloak. The execution sends an email to the current Red Hat build of Keycloak address in order to confirm the user controls that account.

Since this release, the Verify Existing Account By Email execution is only attempted in the First Login Flow if the linking attributes (email and username) sent by the external identity provider are not modified by the user during the review process. This new behavior avoids sending verification emails to an existing Red Hat build of Keycloak account that can inadvertently accept the linking.

In case the provider needs to modify the information sent by the identity provider (because emails or usernames are different in the broker), only the other alternative Verify Existing Account By Re-authentication is available to link the new account to the existing Red Hat build of Keycloak user.

If the data received from the identity provider is mandatory and cannot be modified, the Review Profile step in the First Login Flow can be disabled to avoid any user intervention.

For more information, see the First login flow section of the Server Administration Guide.

When a client is configured to authenticate using the Signed JWT or Signed JWT with Client Secret type, Red Hat build of Keycloak now enforces a maximum expiration for the token. As a result, although the exp (expiration) claim in the token may be much later, Red Hat build of Keycloak does not accept tokens issued before that max expiration time. The default value is 60 seconds.

Note that JWT tokens should be issued right before being sent for authentication. This provides the client with a one-minute window to send the token for login. You can adjust this expiration by using the Max expiration configuration option in the client Credentials tab. For more details, see Confidential client credentials.

In previous releases, the reset credentials flow (forgot password feature) keeps the user logged in after the reset credentials if the same authentication session (same browser) was used. For federated user providers, this behavior can be a security issue. Imagine a provider implementation that detects the user as enabled, performs a successful password change, but the validation of the user password somehow fails. In this scenario, the reset credentials flow allowed a user to log in after a successful password change that would have been disallowed to log in using the normal browser flow. This scenario is an uncommon case, but it should be avoided by default.

In the current release, the authenticator reset-credential-email (Send Reset Email) has a new configuration option called force-login (Force login after reset) with three possible values:

For more details about changing this option, see Enable forgot password.

To favor a more secure server runtime and avoid to accidentally expose system variables, you are now forced to specify which system variables you want to expose by using the spi-admin-allowed-system-variables configuration option when starting the server.

In future releases, this capability will be removed in favor of preventing any usage of system variables in the realm configuration.

With this release, the container images use OpenJDK 21, which provides better performance than OpenJDK 17.

getAll() methods in Organizations and OrganizationMembers APIs are now deprecated and will be removed in the next major release. Instead, use corresponding list(first, max) methods in Organizations and OrganizationMembers APIs.

Potential vulnerable configurations have been identified in the X.509 client certificate lookup when using a reverse proxy. If you have configured the client certificate lookup by a proxy header, additional configuration steps might be required. For more detail, see Enabling client certificate lookup.

In this release, admin events might hold additional details about the context when the event is fired. After the upgrade, you find the database schema has a new column DETAILS_JSON in the ADMIN_EVENT_ENTITY table.

While using the REALM_FILESEPARATOR_KEY key resolver, Red Hat build of Keycloak now restricts access to FileVault secrets outside of its realm. Characters that could cause path traversal when specifying the expression placeholder in the Administration Console are now prohibited.

Additionally, the KEY_ONLY key resolver now escapes the _ character to prevent reading secrets that would otherwise be linked to another realm when the REALM_UNDERSCORE_KEY resolver is used. The escaping simply replaces _ with __, so, for example, ${vault.my_secret} now looks for a file named my__secret. Because this is a breaking change, a warning is logged to ease the transition.

Red Hat build of Keycloak now supports OpenJDK 21. OpenJDK 17 support is deprecated and will be removed in a following release in favor of OpenJDK 21.

Keycloak JavaScript adapter is now a standalone library and is therefore no longer served statically from the Red Hat build of Keycloak server. The goal is to de-couple the library from the Red Hat build of Keycloak server, so that it can be refactored independently, simplifying the code and making it easier to maintain in the future. Additionally, the library is now free of third-party dependencies, which makes it more lightweight and easier to use in different environments.

For a complete breakdown of the changes consult the Upgrading Guide.

This release introduces organizations. The feature leverages the existing Identity and Access Management (IAM) capabilities of Red Hat build of Keycloak to address Customer Identity and Access Management (CIAM) use cases like Business-to-Business (B2B) and Business-to-Business-to-Consumer (B2B2C) integrations. By using the existing capabilities from a realm, the first release of this feature provides the very core capabilities to allow a realm to integrate with business partners and customers:

For more details, see Managing organizations.

You can now have multiple instances of the same social broker in a realm.

Normally, a realm does not need multiple instances of the same social broker. However, with the organization feature, you can link different instances of the same social broker to different organizations.

When creating a social broker, provide an Alias and optionally a Display name just like any other broker.

To help with scaling realms and organizations with many identity providers, the realm representation no longer holds the list of identity providers. However, they are still available from the realm representation when exporting a realm.

For more details, see Identity providers.

Previous versions of Red Hat build of Keycloak stored only offline user and offline client sessions in the databases. The new feature, persistent-user-sessions, stores online user sessions and online client sessions in both memory and the database. As a result, a user can stay logged in even if all instances of Red Hat build of Keycloak are restarted or upgraded.

For more details, see Persistent user sessions.

This feature is enabled by default. If you want to disable it, see the Volatile user sessions procedure in the Configuring distributed caches chapter for more details.

This release introduced the capability to easily add a custom footer to the login pages for the base/login and keycloak.v2/login theme. The new footer.ftl template provides a content macro that is rendered at the bottom of the "login box". To use a custom footer, create a footer.ftl file in your custom login theme with the desired content.

For more details, see Adding a custom footer to a login theme.

The Red Hat build of Keycloak 24 release provided improvements for when a user is authenticated in parallel in multiple browser tabs. However, this improvement did not address the case when an authentication session expired. In this release, when a user is already logged in to one browser tab and an authentication session expired in another browser tab, Red Hat build of Keycloak redirects back to the client application with an OIDC/SAML error. As a result, the client application can immediately retry authentication, which should usually automatically log in the application because of the SSO session.

Note that the message You are already logged in does not appear to the end user when an authentication session expires and user is already logged-in. You may consider updating your applications to handle this error.

For more details, see authentication sessions.

When searching for users by user attribute, Red Hat build of Keycloak no longer searches for user attribute names forcing lower case comparisons. The goal of this change was to speed up searches by using the Red Hat build of Keycloak native index on the user attribute table. If your database collation is case-insensitive, your search results will stay the same. If your database collation is case-sensitive, you might see fewer search results than before.

Red Hat build of Keycloak supports a new password policy that allows you to deny user passwords which contains the user username.

In the Admin Console, you can now configure some actions in the Required actions tab of a particular realm. Currently, the Update password is the only built-in configurable required action. It supports setting Maximum Age of Authentication, which is the maximum time users can update their password by the kc_action parameter (used for instance for a password update in the Account Console) without re-authentication.

The sorting of required actions is also improved. When multiple actions are required during authentication, all actions are sorted together regardless of whether those are actions set during authentication (for instance by the kc_action parameter) or actions added to the user account manually by an administrator.

The default client profile for secured SAML clients was added. When browsing through client policies of a realm in the Admin Console, you see a new client profile saml-security-profile. When it is used, there are security best practices applied for SAML clients. For example, signatures are enforced, SAML Redirect binding is disabled, and wildcard redirect URLs are prohibited.

When a client scope or the full realm is deleted, the associated user consents should also be removed. A new index over the table USER_CONSENT_CLIENT_SCOPE has been added to increase the performance.

Note that, if the table contains more than 300,000 entries, Red Hat build of Keycloak skips the creation of the indexes during the automatic schema migration and logs the SQL statements to the console instead. The statements must be run manually in the database after Red Hat build of Keycloak startup.

Generalized events now exist 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.

Metrics and health checks endpoints are no longer accessible through the standard Red Hat build of Keycloak server port. As these endpoints should be hidden from the outside world, they can be accessed on a separate default management port 9000.

Using a separate port prevents exposure to the users as standard Red Hat build of Keycloak endpoints in Kubernetes environments. The new management interface provides a new set of options, which you can configure.

The Red Hat build of Keycloak Operator assumes the management interface is enabled by default. For more details, see Configuring the Management Interface.

http_server_active_requests 1.0
http_server_requests_seconds_count{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 1.0
http_server_requests_seconds_sum{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 0.048717142

http_server_active_requests 1.0
http_server_requests_seconds_count{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 1.0
http_server_requests_seconds_sum{method="GET",outcome="SUCCESS",status="200",uri="/realms/{realm}/protocol/{protocol}/auth"} 0.048717142

You can use the HTTP Header Accept: application/jwt when invoking a token introspection endpoint. When enabled for a particular client, it returns a claim jwt from the token introspection endpoint with the full JWT access token, which can be useful especially when the client calling introspection endpoint used a lightweight access token.

The support for Passkeys conditional UI was added. When this preview feature is enabled, a dedicated authenticator is available. You can select from a list of available passkeys accounts and authenticate a user based on that.

A new authenticator Confirm override existing link exists. This authenticator allows you to override the linked IDP username for the Red Hat build of Keycloak user, which was previously linked to different IDP identity. For more details, see override existing broker link.

With the goal of improving the scalability of groups, groups are now removed directly from the database when removing a realm. As a result, group-related events, such as the GroupRemovedEvent, are no longer fired when removing a realm.

For information, see Group-related events.

In this release, the LDAP connection pool configuration relies solely on system properties.

For more details, see Configuring the connection pool.

If you are using Microsoft AD and creating users through the administrative interfaces, the user will created as enabled by default.

In previous versions, it was only possible to update the user status after setting a (non-temporary) password to the user. This behavior was not consistent with other built-in user storages as well as not consistent with others LDAP vendors supported by the LDAP provider.

The java-keystore key provider, which allows loading a realm key from an external java keystore file, has been modified to manage all Red Hat build of Keycloak algorithms. Also, the keystore and key secrets, which are needed to retrieve the actual key from the store, can be configured using the vault. Therefore, a Red Hat build of Keycloak realm can externalize any key to the encrypted file without sensitive data stored in the database.

For more information about this subject, see Configuring realm keys.

In previous versions, the session max lifespan and idle timeout calculation was slightly different when validating if a session was still valid. Now that validation uses the same code as the rest of the project.

If the session is using the remember me feature, the idle timeout and max lifespan are the maximum value between the common SSO and the remember me configuration values.

Due to the complexity of the hostname configuration settings, this release includes Hostname v2 options. The original host name options have been removed. If you have custom hostname settings, you should migrate to the new options. Note that the behavior behind these options has also changed.

For more details, see New hostname options.

You can now specify the cache, cache-stack, and cache-config-file options during runtime. This change eliminates the need to execute the build phase and rebuild your image with these options.

For more details, see Specify cache options at runtime.

Red Hat build of Keycloak 26 introduces significant improvements to the recommended high availability multi-site architecture, most notably:

For details on implementation, see Highly available multi-site deployments.

As a consequence of the removal of deprecated methods from AccessToken, IDToken, and JsonWebToken, the SingleUseObjectKeyModel also changed to keep consistency with the method names related to expiration values.

For more details, see SingleUseObjectKeyModel.

The supported and tested databases now include PostgreSQL 16.

Marshalling is the process of converting Java objects into bytes to send them across the network between Red Hat build of Keycloak servers. With Red Hat build of Keycloak 26, the marshalling format is changed from JBoss Marshalling to Infinispan Protostream.

Infinispan Protostream is based on Protocol Buffers (proto 3), which has the advantage of backwards/forwards compatibility.

In previous releases, regaining access to a Red Hat build of Keycloak instance when all admin users were locked out was a challenging process. However, Red Hat build of Keycloak now offers new methods to bootstrap a temporary admin account and recover lost admin access.

You can now run the start or start-dev commands with specific options to create a temporary admin account. Also, a new dedicated command is introduced, allowing users to quickly regain admin access.

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 temporary admin account.

The underlying Quarkus support for OpenTelemetry Tracing has been exposed to Red Hat build of Keycloak and allows you to obtain application traces for better observability. This feature includes the ability to locate performance bottlenecks, determine the cause of application failures, and trace a request through the distributed system.

For more information, see Enabling tracing.

The DPoP (OAuth 2.0 Demonstrating Proof-of-Possession) preview feature has improvements. The DPoP is now supported for all grant types. With previous releases, this feature was supported only for the authorization_code grant type. Support also exists for the DPoP token type on the UserInfo endpoint.

Now Red Hat build of Keycloak allows configuring ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW or ECDH-ES+A256KW as the encryption key management algorithm for clients. The Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) specification introduces three new header parameters for the JWT: epk, apu and apv. Currently Red Hat build of Keycloak implementation only manages the compulsory epk while the other two (which are optional) are never added to the header. For more information about those algorithms please refer to the JSON Web Algorithms (JWA).

Also, a new key provider, ecdh-generated, is available to generate realm keys and support for ECDH algorithms is added into the Java KeyStore provider.

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.

For more details, see Persisting removed access tokens.

The condition based on the client-attribute was added into Client Policies. You can use this condition to specify for the clients with the specified client attribute having a specified value. Use either an AND or OR condition when evaluating this condition as mentioned in the documentation for client policies.

Now Red Hat build of Keycloak allows configuring ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW or ECDH-ES+A256KW as the encryption key management algorithm for clients. The Key Agreement with Elliptic Curve Diffie-Hellman Ephemeral Static (ECDH-ES) specification introduces three new header parameters for the JWT: epk, apu and apv. Currently, Red Hat build of Keycloak implementation only manages the compulsory epk while the other two (which are optional) are never added to the header. For more information about those algorithms, see the JSON Web Algorithms (JWA).

Also, a new key provider, ecdh-generated, is available to generate realm keys and support for ECDH algorithms is added into the Java KeyStore provider.

The proxy-trusted-addresses can be used when the proxy-headers option is set to specify an allowlist of trusted proxy addresses. If the proxy address for a given request is not trusted, then the respective proxy header values will not be used. For details, see Trusted Proxies.

The proxy-protocol-enabled option controls whether the server should use the HA PROXY protocol when serving requests from behind a proxy. When set to true, the remote address returned will be the one from the actual connecting client. For details, see Proxy Protocol.

The https-certificates-reload-period option can be set to define the reloading period of key store, trust store, and certificate files referenced by https-* options. Use -1 to disable reloading. Defaults to 1h (one hour). For details, see Certificate and Key Reloading.

The --cache-embedded-${CACHE_NAME}-max-count= can be set to define an upper bound on the number of cache entries in the specified cache.

Based on the community feedback, we decided to undeprecate https-trust-store-* options to allow better granularity in trusted certificates.

org.keycloak.common.util.Resteasy has been deprecated. You should use the org.keycloak.util.KeycloakSessionUtil to obtain the KeycloakSession instead.

It is highly recommended to avoid obtaining the KeycloakSession by means other than when creating your custom provider.

The origin property in the UserRepresentation is deprecated and planned to be removed in a future release.

Instead, prefer using the federationLink property to obtain the provider to which a user is linked with.

The following items have been deprecated for removal in upcoming Red Hat build of Keycloak versions with no replacement:

The class UserSessionCrossDCManager is deprecated and planned to be removed in a future version of Red Hat build of Keycloak. Read the UserSessionCrossDCManager Javadoc for the alternative methods to use.

The Account REST endpoint for removing the credential of the user is deprecated. Starting at this version, the Account Console no longer uses this endpoint. It is replaced by the Delete Credential application-initiated.

The keycloak login theme has been deprecated in favor of the new keycloak.v2 and will be removed in a future version. While it remains the default for the new realms for compatibility reasons, it is strongly recommended to switch all the realm themes to keycloak.v2.

Method String encode(String rawPassword, int iterations) on the interface org.keycloak.credential.hash.PasswordHashProvider is deprecated. The method will be removed in one of the future Red Hat build of Keycloak releases.

The following variables were deprecated in the Admin theme and will be removed in a future version:

The following variables were deprecated in the Account theme and will be removed in a future version:

The methods String getCurrentRefreshToken(), void setCurrentRefreshToken(String currentRefreshToken), int getCurrentRefreshTokenUseCount(), and void setCurrentRefreshTokenUseCount(int currentRefreshTokenUseCount) in the interface org.keycloak.models.AuthenticatedClientSessionModel are deprecated. They have been replaced by similar methods that require an identifier as a parameter such as getRefreshToken(String reuseId) to manage multiple refresh tokens within a client session. The methods will be removed in one of the future Red Hat build of Keycloak releases.

The UMD distribution Universal Module Definition of the Keycloak JS library has been removed. This means that the library is no longer exposed as a global variable, and instead must be imported as a module. This change is in line with modern JavaScript development practices, and allows for a more consitent experience between browsers and build tooling, and generally results in more predictable code with less side-effects.

If you are using a bundler such as Vite or Webpack nothing changes, you’ll have the same experience as before. If you are using the library directly in the browser, you’ll need to update your code to import the library as a module:

<!-- Before -->
<script src="/path/to/keycloak.js"></script>
<script>
    const keycloak = new Keycloak();
</script>

<!-- After -->
<script type="module">
    import Keycloak from '/path/to/keycloak.js';
    const keycloak = new Keycloak();
</script>

<!-- Before -->
<script src="/path/to/keycloak.js"></script>
<script>
    const keycloak = new Keycloak();
</script>

<!-- After -->
<script type="module">
    import Keycloak from '/path/to/keycloak.js';
    const keycloak = new Keycloak();
</script>

You can also opt to use an import map make the import of the library less verbose:

<script type="importmap">
    {
        "imports": {
            "keycloak-js": "/path/to/keycloak.js"
        }
    }
</script>
<script type="module">
    // The library can now be imported without specifying the full path, providing a similar experience as with a bundler.
    import Keycloak from 'keycloak-js';
    const keycloak = new Keycloak();
</script>

<script type="importmap">
    {
        "imports": {
            "keycloak-js": "/path/to/keycloak.js"
        }
    }
</script>
<script type="module">
    // The library can now be imported without specifying the full path, providing a similar experience as with a bundler.
    import Keycloak from 'keycloak-js';
    const keycloak = new Keycloak();
</script>

If you are using TypeScript you may need to update your tsconfig.json to be able to resolve the library:

{
    "compilerOptions": {
        "moduleResolution": "Bundler"
    }
}

{
    "compilerOptions": {
        "moduleResolution": "Bundler"
    }
}

The method org.keycloak.common.util.CollectionUtil.intersection has been removed. You should use the 'java.util.Collection.retainAll' instead on an existing collection.

The Account Console v2 theme has been removed from Red Hat build of Keycloak. This theme was deprecated in Red Hat build of Keycloak 24 and replaced by the Account Console v3 theme. If you are still using this theme, you should migrate to the Account Console v3 theme.

These options were replaced by new options referred to as Hostname v2. For more details, see Configuring the hostname (v2) and New hostname options.

The proxy option was deprecated in Red Hat build of Keycloak 24 and was replaced by the proxy-headers option in combination with hostname options as needed. For more details, see Using a reverse proxy.

Most Java adapters are now removed from the Red Hat build of Keycloak codebase and downloads pages.

Since all of the Java adapters that used OSGi metadata have been removed, OSGi metadata are no longer generated for our jars.

Red Hat build of Keycloak no longer sends _LEGACY cookies, which where introduced as a work-around to older browsers not supporting the SameSite flag on cookies.

The _LEGACY cookies also served another purpose, which was to allow login from an insecure context. Although an insecure context is never recommended in production deployments of Red Hat build of Keycloak, it is fairly frequent to access Red Hat build of Keycloak over http outside of localhost. As an alternative to the _LEGACY cookies, Red Hat build of Keycloak no longer sets the secure flag; but it does set SameSite=Lax instead of SameSite=None when it detects an insecure context is used.

The method EnvironmentDependentProviderFactory.isSupported() was deprecated for several releases and has now been removed.

Instead, implement isSupported(Config.Scope config).

Previous versions of Red Hat build of Keycloak 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 Red Hat build of Keycloak 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 OpenID Connect RP-Initiated Logout specification instead.

The module org.keycloak:keycloak-model-legacy module was deprecated in a previous release and is removed in this release. Use the org.keycloak:keycloak-model-storage module instead.

The old behavior to preload offline sessions at startup is now removed after it has been deprecated in the previous release.

The groups.setOrCreateChild() method has been removed from that JavaScript-based Admin Client. If you are still using this method, start using the createChildGroup() or updateChildGroup() methods instead.

The session_state claim, which contains the same value as the sid claim, is now removed from all tokens as it is not required according to the OpenID Connect Front-Channel Logout and OpenID Connect Back-Channel Logout specifications. The session_state claim remains present in the Access Token Response in accordance with OpenID Connect Session Management specification.

Note that the setSessionState() method is also removed from the IDToken class in favor of the setSessionId() method, and the getSessionState() method is now deprecated.

A new Session State (session_state) mapper is also included and can be assigned to client scopes (for instance basic client scope) to revert to the old behavior.

If an old version of the JS adapter is used, the Session State (session_state) mapper should also be used by using client scopes as described above.

Previous versions of Red Hat build of Keycloak added a grace period of two minutes to idle times of user and client sessions. This was added due to a previous architecture where session refresh times were replicated asynchronously in a cluster. With persistent user sessions, this is no longer necessary, and therefore the grace period is now removed.

To keep the old behavior, update your realm configuration and extend the session and client idle times by two minutes.

The org.keycloak.bom:keycloak-adapter-bom and org.keycloak.bom:keycloak-misc-bom BOM files are removed. The adapter BOM was no longer useful because most of the Java adapters are removed. The misc BOM had contained only one artifact, keycloak-test-helper, and that artifact is also removed in this release.

The maven artifact org.keycloak:keycloak-test-helper is removed in this release. The artifact provided a few helper methods for dealing with a Java admin client. If you use the helper methods, it is possible to fork them into your application if needed.

The JEE admin-client is removed in this release, however, the Jakarta admin-client is still supported.

The following methods were removed from the AccessToken class:

The following methods were removed from the IDToken class:

The following methods were removed from the JsonWebToken class:

You should also expect both exp and nbf claims not set in tokens as they are optional. Previously, these claims were being set with a value of 0 what does not make mush sense because their value should be a valid NumericDate.

The following APIs for setting custom cookies have been removed:

In version 22.0, the OAuh 2.0 social provider for LinkedIn was replaced by a new OpenId Connect implementation. The legacy provider was deprecated but not removed, just in case it was still functional in some existing realms. Red Hat build of Keycloak 26 is removing the old provider and its associated linkedin-oauth feature. From now on, the default LinkedIn social provider is the only option available.