Upgrading Guide

Since this release, Red Hat build of Keycloak adds a new option allowutf8 for the realm SMTP configuration (Allow UTF-8 field inside the Email tab in the Realm settings section of the Admin Console). For more information about email configuration, see the Configuring email for a realm chapter in the Server Administration Guide.

Enabling the option encodes email addresses in UTF-8 when sending them, but it depends on the SMTP server to also supports UTF-8 via the SMTPUTF8 extension. If Allow UTF-8 is disabled, Red Hat build of Keycloak will encode the domain part of the email address (second part after @) using punycode if non-ASCII characters are used, and will reject email addresses that use non-ASCII characters in the local part.

If you have an SMTP server configured for your realm, perform the following migration after the upgrade:

If you are upgrading Red Hat build of Keycloak by downloading the distribution, the upgrade procedure has been changed. Previously, that procedure recommended copying over the contents of the conf/ folder from the old to the new installation. The new procedure recommends that you re-apply any changes to cache-ispn.xml or a custom cache configuration based on the file included in the new version.

This step prevents you from accidentally downgrading functionality, for example, by using an old cache-ispn.xml file from a previous version.

Previous versions of Red Hat build of Keycloak warned about problematic configurations, for example, if a wrong number of owners was configured or a cache size was set when it should not have been set when enabling volatile user sessions. The docs also stated to update the cache-ispn.xml configuration file for volatile user sessions.

The current version will always use safe settings for the number of owners and maximum cache size for the affected user and client session caches, and will log only an INFO message. With this behavior, there is no need any more to update the cache-ispn.xml configuration file. If you previously used a custom cache-ispn.xml in order to use volatile user sessions, we recommend reverting those changes and use the standard configuration file.

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, then 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.

The user-profile-commons.ftl changed to improve support for localization. As a result of this change, pages might start displaying a locale field if you extend this template. To avoid that situation, update the theme template with the changes aforementioned.

The X-Forwarded-Host header can optionally also contain the port. In previous versions when the port was omitted from the header, Red Hat build of Keycloak fell back to the actual request port. For example if Red Hat build of Keycloak was listening on port 8080 and the request contained X-Forwarded-Host: example.com header, the resolved URL was http://example.com:8080.

This is now changed and omitting the port results in removing it from the resolved URL. The resolved URL from the previous example would now be http://example.com.

To mitigate that, either make your reverse proxy include the port in the X-Forwarded-Host header or configure it to set the X-Forwarded-Port header with the desired port.

The required JAR for the Oracle JDBC driver that needs to be explicitly added to the distribution has changed. Instead of providing ojdbc11 JAR, use ojdbc17 JAR as stated in Installing the Oracle Database driver.

With this version, the default H2 based dev-file database changed its credentials. While migrating from an instance using this dev only database is not supported, you may be able to continue to use your existing H2 database if you explicitly provide the old defaults for the database username and password. For example in the keycloak.conf specify:

The latest draft version of the OpenID Connect core specification changed the rules for audience validation in JWT client assertions for the Client Authentication methods private_key_jwt and client_secret_jwt.

Previously, the aud claim of a JWT client assertion was loosely defined as The Audience SHOULD be the URL of the Authorization Server’s Token Endpoint, which did not exclude the usage of other URLs.

The revised OIDC Core specification uses a stricter audience check: The Audience value MUST be the OP’s Issuer Identifier passed as a string, and not a single-element array..

We adapted the JWT client authentication authenticators of both private_key_jwt and client_secret_jwt to allow only a single audience in the token by default. For now, the audience can be the issuer, token endpoint, introspection endpoint or some other OAuth/OIDC endpoint, which is used by client JWT authentication. However since there is single audience allowed now, it means that it is not possible to use other unrelated audience values, which is to make sure that JWT token is really only useful by the Red Hat build of Keycloak for client authentication.

This strict audience check can be reverted to the previous more lenient check with a new option of OIDC login protocol SPI. It will be still allowed to use multiple audiences in JWT if server is started with the option:

--spi-login-protocol-openid-connect-allow-multiple-audiences-for-jwt-client-authentication=true

Note that this option might be removed in the future. Possibly in Red Hat build of Keycloak 27. So it is highly recommended to update your clients to use a single audience instead of using this option. It is also recommended that your clients use the issuer URL for the audience when sending JWT for client authentication as that is going to be compatible with the future version of OIDC specification.

At version 26.2.x, the following changes are major improvements that provide new support for existing features.

In this release, Red Hat build of Keycloak added support for the Standard token exchange (Feature token-exchange-standard:v2). In the past Red Hat build of Keycloak releases, Red Hat build of Keycloak had only a preview token exchange feature, which is now referred to as Legacy token exchange (Feature token-exchange:v1). The legacy token exchange is still in preview and it works the same way as in previous releases. If you used the internal-internal token exchange,consider migrating to the new standard token exchange.

If you prefer to continue using the legacy token exchange, no need exists to disable the standard token exchange feature. Your clients will use the standard token exchange only if it is enabled on the Red Hat build of Keycloak client. However, migration to the standard token exchange is recommended. It is the officially supported method and the priority for enhancements.

Consider the following notes as you plan for migration to the new standard token exchange:

Consider these additional changes in the behavior of the two types of token exchange:

Currently, it is not supported to request offline tokens or exchange a refresh token when the subject token was issued from an offline session. The recommended approach is to exchange for access tokens instead of a refresh token when possible.

Red Hat build of Keycloak introduces fine-grained admin permissions V2, offering an improved and more flexible authorization model for administrative permissions.

For clustering multiple nodes, Red Hat build of Keycloak uses distributed caches. Starting with this release for all TCP-based transport stacks, the communication between the nodes is encrypted with TLS and secured with automatically generated ephemeral keys and certificates.

If you are not using a TCP-based transport stack, it is recommended to migrate to the jdbc-ping transport stack to benefit from the simplified configuration and enhanced security.

If you provided your own keystore and truststore to secure the TCP transport stack communication in previous releases, it is now recommended to migrate to the automatically generated ephemeral keys and certificates to benefit from the simplified setup.

If you are using a custom transport stack, this default behavior can be disabled by setting the option cache-embedded-mtls-enabled to false.

If you are using a service mesh, configure it to allow direct mTLS communication between the Red Hat build of Keycloak Pods.

For more details, see Securing Transport Stacks.

When adding new users, groups, or roles, the LDAP provider would always store them in the same base DN configured for the searches. However, in some deployments admins may want to configure a broader DN with subtree scope to fetch users (or groups/roles) from multiple sub-DNs, but they do not want new users (or groups/roles) to be stored in this base DN in LDAP. Instead, they would like to choose one of the sub-DNs for that.

It is now possible to control where new users, groups, or roles will be created using the new Relative User Creation DN config option in the LDAP provider and also in the LDAP group and role mappers. For more details, see LDAP admin

Built-in X.509 client certificate lookup providers now reflect the proxy-trusted-addresses config option. A certificate provided through the HTTP headers will now be processed only if the proxy is trusted, or proxy-trusted-addresses is unset.

The Red Hat build of Keycloak Operator now creates by default a NetworkPolicy to restrict traffic to internal ports used for Red Hat build of Keycloak’s distributed caches.

This strengthens a secure-by-default setup and minimizes the configuration steps of new setups. This change is intended to be backwards compatible to existing deployment, so no additional steps are necessary at the time of the upgrade. You can return to the previous behavior by disabling the creation of NetworkPolicies in the Keycloak CR.

If your deployment scripts add explicit NetworkPolicies for Red Hat build of Keycloak, consider removing those and migrate to the new functionality provided in the Keycloak CR as a follow-up to the upgrade.

For more details, see Operator Advanced configuration.

Previously the reset credentials flow (forgot password feature) kept 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. Consider a scenario where a provider implementation detects the user as enabled and performs the password change successfully, but somehow the validation of the user password fails. In this scenario, the reset credentials flow allowed a user to log in after the successful password change; however, that login would have been denied using the normal browser flow. This is not a common scenario, but it should be avoided by default.

For this reason, now the authenticator reset-credential-email (Send Reset Email) has a new configuration option called force-login (Force login after reset) with values true (always force the login), false (previous behavior that keeps the user logged in if the same authentication session is used), and only-federated (default value that forces federated users to authenticate again and keeps the previous behavior for users stored in Red Hat build of Keycloak’s internal database).

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

Any offline session in Red Hat build of Keycloak is created from an online session. When the offline_access scope is requested, the current online session is used to create the associated offline session for the client. Therefore, any offline_access request finished, until now, created two sessions: one online and one offline. This situation leads to unreliable behavior. For example, when just the login with scope=offline_access was requested, an unused online session could be created. This session is useless in most cases and causes unnecessary consumption of server resources.

Starting with this version, Red Hat build of Keycloak removes the initial online session if the offline_scope is directly requested as the first interaction for the session. The client retrieves the offline token after the code to token exchange that is associated to the offline session, but the previous online session is removed. If the online session has been used before the offline_scope request, by the same or another client, the online session remains active as today. This situation also means that the SSO session is not created in the browser if the login request with scope=offline_access is used and the user was not already authenticated in the SSO beforehand. Although the new behavior makes sense because the client application is just asking for an offline token, it can affect some scenarios that rely on having the online session still active after the initial offline_scope token request.

Red Hat build of Keycloak introduces a new client scope at the realm level called service_account. This scope is in charge of adding the specific claims for the client_credentials grant (client_id, clientHost and clientAddress) by using protocol mappers. This scope will be automatically assigned to and unassigned from the client when the serviceAccountsEnabled option is set or unset in the client configuration.

Previously, the three mappers (Client Id, Client Host and Client IP Address) were added directly to the dedicated scope when the client was configured to enable service accounts, and they were never removed.

The behavior should be effectively the same for most Red Hat build of Keycloak deployments because claims in the token are effectively the same as before. You might be affected in cases when you are using a client credentials grant and you are preparing the Red Hat build of Keycloak environment by some tooling that is manually removing or updating the three protocol mappers mentioned above. For instance, if you use an admin CLI script to enable a service-account for a client and then remove the built-in service-account protocol mappers, you may adjust your CLI to instead remove the assignment of the service_account client scope from the client instead of removing protocol mappers.

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. This means that, although the exp (expiration) claim in the token may be much later, Red Hat build of Keycloak will 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. As a result, the client has a one minute window to send the token for login. Nevertheless this expiration can be tuned using the Max expiration configuration option on the client Credentials tab. For more details, see Confidential client credentials.

At version 26.2.x, certain features have been removed and other features have been marked as deprecated for removal at a later release. For details on these changes, see the Release Notes.

To perform an automatic migration, start the server connected to the desired database. If the database schema has changed for the new server version, the migration starts automatically unless the database has too many records.

For example, creating an index on tables with millions of records can be time-consuming and cause a major service disruption. Therefore, a threshold of 300000 records exists for automatic migration. If the number of records exceeds this threshold, the index is not created. Instead, you find a warning in the server logs with the SQL commands that you can apply manually.

To change the threshold, set the index-creation-threshold property, value for the connections-liquibase provider:

kc.[sh|bat] start --spi-connections-liquibase-quarkus-index-creation-threshold=300000

kc.[sh|bat] start --spi-connections-liquibase-quarkus-index-creation-threshold=300000

To enable manual upgrading of the database schema, set the migration-strategy property value to "manual" for the default connections-jpa provider:

kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-strategy=manual

When you start the server with this configuration, the server checks if the database needs to be migrated. If migration is needed, the required changes are written to the bin/keycloak-database-update.sql SQL file. You can review and manually run these commands against the database.

To change the path and name of the exported SQL file, set the migration-export property for the default connections-jpa provider:

kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

kc.[sh|bat] start --spi-connections-jpa-quarkus-migration-export=<path>/<file.sql>

For further details on how to apply this file to the database, see the documentation for your relational database. After the changes have been written to the file, the server exits.

If you customized any template, compare it to the new version of that template. This comparison shows you what changes you need to apply to your customized template. You can use a diff tool to compare the templates. The following screenshot compares the info.ftl template from the Login theme and an example custom theme:

This comparison shows that the first change (Hello world!!) is a customization, while the second change (if pageRedirectUri) is a change to the base theme. By copying the second change to your custom template, you have successfully updated your customized template.

In an alternative approach, the following screenshot compares the info.ftl template from the old installation with the updated info.ftl template from the new installation:

This comparison shows what has been changed in the base template. You can then manually make the same changes to your modified template. Since this approach is more complex, use this approach only if the first approach is not feasible.

If you added support for another language, you need to apply all the changes listed above. If you have not added support for another language, you might not need to change anything. You need to make changes only if you have changed an affected message in your theme.

You might need to update your custom styles to reflect changes made to the styles from the built-in themes. Consider using a diff tool to compare the changes to stylesheets between the old server installation and the new server installation.

For example:

diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

$ diff RHSSO_HOME_OLD/themes/keycloak/login/resources/css/login.css \
RHSSO_HOME_NEW/themes/keycloak/login/resources/css/login.css

Review the changes and determine if they affect your custom styling.