Upgrading Guide

Now Red Hat build of Keycloak, when acting as a SAML Service Provider (SP) in identity brokering or in the adapter, validates the

SubjectConfirmationData

urn:oasis:names:tc:SAML:2.0:cm:bearer

NotBefore

NotOnOrAfter

Recipient

Conditions

destination

To prepare for the upgrade, verify that the Identity Provider or adapter configurations allow for a sufficient clock skew for the time attributes.

If you see any issue after the upgrade related to this element, please configure the external IdP to set the correct values for the subject confirmation element.

In the previous release, Red Hat build of Keycloak accepted HTTP requests with paths containing double dots (

..

//

To analyze rejected requests in the server log, enable debug logging for

org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter

To revert to the previous behavior and to accept non-normalized URLs, set

http-accept-non-normalized-paths

true

The

acr_values

If you are relying on the

acr_values

acr_values

Forwarded query parameters

In some previous versions of Red Hat build of Keycloak, the EnterpriseDB (EDB) was considered unsupported. This has now changed and EDB Advanced is supported starting with this release. If the EDB JDBC driver was used for connecting to EDB in previous versions, some invalid schema changes were applied to the database. To mitigate this, some indexes are automatically re-created during the schema migration to this version. This affects you if you are using a PostreSQL database (including EDB), regardless if you used EDB with previous releases.

This affects indexes on the

CLIENT_ATTRIBUTES

GROUP_ATTRIBUTE

In previous releases, the only possible way to configure additional datasources was using raw Quarkus properties that are generally considered unsupported. At the same time, adding additional datasources was supported which led to unclear situation.

To provide a supported and user-friendly way to configure additional datasources, we introduced new dedicated server options for that. Configuring additional datasources using the original approach via the Quarkus properties is considered unsupported starting with this release.

Check the following examples on how to migrate your configuration:

In previous releases there was an inconsistency in the REST endpoint result of getting a user (

GET /admin/realms/{realm}/users/{user-id}

GET /admin/realms/{realm}/users

enabled=false

enabled=true

enabled=true

GET /admin/realms/{realm}/attack-detection/brute-force/users/{userId}

When querying users through the User API, the user representation and their attributes are now taking into account the user profile settings defined for the realm.

It might happen that attributes in user representations are no longer available depending on the user profile configuration where too much information was returned in the past.

In a scenario where Red Hat build of Keycloak acts as a broker and connects by OpenID Connect to another identity provider, it now sends the client credentials by basic authentication in the correct encoding as specified in RFC6749. You are not affected if you configured Red Hat build of Keycloak to send the credentials in the request body.

This prevents problems with client IDs or passwords that contain, for example, a colon or a percentage sign.

To revert to the old behavior, change the client authentication to the deprecated option Client secret sent as HTTP Basic authentication without URL encoding (client_secret_basic_unencoded).

Since this release, the Red Hat build of Keycloak SAML implementation limits the data that can be inflated through the

REDIRECT

spi-login-protocol—​saml—​max-inflating-size

bin/kc.[sh|bat] --spi-login-protocol--saml--max-inflating-size=524288

The same restriction is applied for the SAML Galleon feature pack. Although, in this case, you need to add a system property to the EAP server to change the default maximum size:

-Dorg.keycloak.adapters.saml.maxInflatingSize=524288

Previously virtual threads were used when at least two CPU cores were available. Starting with this version, virtual threads are only used when at least four CPU cores are available. This change should prevent deadlocks due to pinned virtual threads.

If you are running on PostgreSQL as a database for Red Hat build of Keycloak, ensure that the database user has

SELECT

pg_class

pg_namespace

This is used during upgrades of Red Hat build of Keycloak to determine an estimated number of rows in a table. If Red Hat build of Keycloak does not have permissions to access these tables, it will log a warning and proceed with the less efficient

SELECT COUNT(*) ...

Previously Red Hat build of Keycloak accepted HTTP requests with paths containing a semicolon (

;

To analyze rejected requests in the server log, enable debug logging for

org.keycloak.quarkus.runtime.services.RejectNonNormalizedPathFilter

To revert to the previous behavior and to accept matrix parameters set the option

http-accept-non-normalized-paths

true

The

BROKER_LINK

IDX_BROKER_LINK_USER_ID

IDX_BROKER_LINK_IDENTITY_PROVIDER

If the table contains more than 300,000 entries, Red Hat build of Keycloak will skip the index creation by default during the automatic schema migration and instead log the SQL statement on the console during migration to be applied manually after Red Hat build of Keycloak’s startup. For details on configuring a different limit, see Migrating the database.

LDAP referrals now by default are only allowed to include LDAP URLs. This change enhances security and aligns with best practices for LDAP configurations.

This change also prevents other JDNI references from being used in case you have written custom extensions. To restore the original behavior, set the option

spi-storage—​ldap—​secure-referral

false

In previous versions, realm administrators granted with the

realm-admin

admin

In this release, realm administrators with the

realm-admin

If you are using FGAP to delegate administration to users in a realm other than the master realm, make sure the users granted with the

realm-admin

For more details on different types of realm administrators, see Delegating realm administration using permissions.

This change adds new indexes on the

OFFLINE_CLIENT_SESSION

If those tables contain more than 300,000 entries, Red Hat build of Keycloak skips the index creation during the automatic schema migration. Instead, the migration displays the required SQL statement to be applied manually after startup of Red Hat build of Keycloak. For details on configuring a different limit, see Migrating the database.

If you are upgrading Red Hat build of Keycloak by downloading the distribution, the upgrade procedure has been changed. Previously it recommended copying over the contents from the

conf/

cache-ispn.xml

This prevents accidentally downgrading functionality, for example, by using an old

cache-ispn.xml

The supported version of each database is now shown in Configuring the database. However, it is not a supported configuration if the underlying database specific Hibernate dialect allows the use of a version that differs from those shown.

If you are querying users by attributes through the User API where you want to fetch users that match a specific attribute key (regardless the value), consider setting the

exact

false

/admin/realms/{realm}/users

GET

For instance, searching for all users with the attribute

myattribute

GET /admin/realms/{realm}/users?exact=false&q=myattribute:

The Red Hat build of Keycloak Admin Client is also updated with a new method to search users by attribute using the

exact

When the "Remember Me" option is disabled in the realm settings, all user sessions previously created with the "Remember Me" flag are now considered invalid. Users will be required to log in again, and any associated refresh tokens will no longer be usable. User sessions created without selecting "Remember Me" are not affected.

When running PostgreSQL reader and writer instances, Red Hat build of Keycloak needs to always connect to the writer instance to do its work.

Starting with this release, and when using the original PostgreSQL driver, Red Hat build of Keycloak sets the

targetServerType

primary

You can override this behavior by setting your own value for

targetServerType

The

EVENT_ENTITY

IDX_EVENT_ENTITY_USER_ID_TYPE

USER_ID

TYPE

EVENT_TIME

If the table contains more than 300,000 entries, Red Hat build of Keycloak skips the index creation during the automatic schema migration. However, the SQL statement appears on the console during migration so you can apply it manually after Red Hat build of Keycloak startup. For details on configuring a different limit, see Migrating the database.

If you are running Red Hat build of Keycloak in FIPS 140-2 mode, update your Bouncy Castle libraries to the versions listed in the release documentation.

With the upgrade to Bouncy Castle 2.1.x, EdDSA is now supported in FIPS 140-2 mode.

When using remote caches, Red Hat build of Keycloak now automatically creates the necessary caches during startup if they do not already exist on the Data Grid server.

For a multi-cluster setup, it is still recommended to create the caches using Cache CRs in advance to verify the correct initialization of the caches and to avoid start-up errors while the caches are present in only one of the sites.

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 documentation also stated to update the

cache-ispn.xml

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, you no longer need to update the

cache-ispn.xml

cache-ispn.xml

The

conf/cache-ispn.xml

--cache-config-mutate=true

When upgrading an existing deployment, remove all default cache configurations from your existing

conf/cache-ispn.xml

--cache-...

In order to prevent connections being closed unexpectedly by the database server, it is necessary to ensure that the Red Hat build of Keycloak connection pool is correctly configured with respect to the server’s

wait_timeout

Starting with this release, Red Hat build of Keycloak defines a default

db-pool-max-lifetime

wait_timeout

If the server defines a

wait_timeout

db-pool-max-lifetime

Red Hat build of Keycloak now exposes an RFC8414-compliant endpoint at the root URL level

/.well-known/

As an example, OAuth 2.0 Authorization Server Metadata information was exposed by this URL:

https://keycloak.example.com/realms/{realm}/.well-known/oauth-authorization-server

It is now available also by this URL:

https://keycloak.example.com/.well-known/oauth-authorization-server/realms/{realm}

To benefit from this, expose the path

/.well-known/

http-relative-path

/.well-known/

The default scheduling strategy has been updated so that a topology spread constraint is created for both zones and nodes in order to increase availability in the presence of failures. Previously, the default strategy preferred that all nodes were deployed to the same availability zone. For more details, see the High Availability Guide.

Previously, configuring JGroups network addresses and ports required that you use the

jgroups.bind.*

jgroups.external_*

Configuring ports using the old properties has not changed, but using the CLI options is recommended because the previous method could be deprecated.

The cache key of the authenticated client sessions has changed for embedded Infinispan, while the public APIs have not changed. Due to this, you should not run 26.4.1 concurrently in a cluster with previous versions.

When using the

/realms/{realm-name}/broker/{provider_alias}/token

When using GitHub as an IDP, you can now enable JSON responses to leverage the token refresh for this endpoint.

The batching of persistent user session updates has been turned off by default because it negatively impacts performance with some database vendors, which offsets the benefits with other database vendors. You can enable batching by using the CLI option

--spi-user-sessions—​infinispan—​use-batches=true

The name of the session note is now shown as a required field in the Admin Console.

The name of the token claim is now shown as a required field in the Admin Console.

Starting with this release, Red Hat build of Keycloak caches by default only 10,000 entries for offline user and client sessions in memory when volatile user sessions are enabled. This change greatly reduces memory usage.

To change the size of the offline session caches, use the

cache-embedded-offline-sessions-max-count

cache-embedded-offline-client-sessions-max-count

The naming of resource bundles in classloader and folder based themes is now aligned with Java ResourceBunndle#getBundle file names. For all included community languages, such as

de

pt-BR

messages_de.properties

messages_pt_BR.properties

The "Chinese (traditional)" and "Chinese (simplified)" languages are named for historical reasons

zh-TW

zh-CN

zh-Hant

zh-Hans

zh-TW

zh-CN

messages_zh_Hant.properties

messages_zh_Hant.properties

messages_zh_Hant.properties

messages_zh_TW.properties

messages_zh_Hans.properties

messages_zh_CN.properties

When a SAML client was enabled to Encrypt Assertions, the assertion included in the SAML response was encrypted following the XML Encryption Syntax and Processing specification. The algorithms used for encryption were fixed and outdated. Starting with this release, default encryption options are up to date and better suited in terms of security. In addition, if a specific client needs a different algorithm, you can configure the encryption details. You define new attributes in the client to specify the exact algorithms used for encryption. In the Admin Console, when Encrypt Assertions is enabled in the Keys tab, these attributes appear in the client Settings tab, Signature and Encryption section.

To maintain backwards compatibility, the Red Hat build of Keycloak upgrade modifies the existing SAML clients to set the encryption attributes to work as before. As a result, existing clients receive the same encrypted assertion using the same previous algorithms. If the client supports the new default configuration, removing the attributes is recommended.

For more information about client configuration, see Creating a SAML client.

When validating an email address as a required action or an application initiated action, a user can resend the verification email by default only every 30 seconds, while in earlier versions no limitation existed for re-sending the email.

Administrators can configure the interval per realm in the Verify Email required action in the Authentication section of the realm.

When tracing is enabled, calls to other nodes of a Red Hat build of Keycloak cluster now create spans in the traces.

To disable this kind of tracing, set the option

tracing-infinispan-enabled

false

If no value is specified either on the LDAP configuration as the connectionTimeout or by the

com.sun.jndi.ldap.connect.timeout

The input fields in the login theme for OTP and recovery codes and have been optimized:

When the OIDC authentication request (or OAuth2 authorization request) is sent, a new limit exists for the maximum length of every standard OIDC/OAuth2 parameter. The maximum length of each standard parameter is 4,000 characters, which is a very large number that may be lowered in a future release. For now, it remains large for backwards compatibility. The only exception is the

login_hint

username

email

If you want to increase or lower those numbers, start the server with the option

req-params-default-max-size

req-params-max-size

login-protocol

Starting with this release, Red Hat build of Keycloak adds a new option

allowutf8

Enabling the option encodes email addresses in UTF-8 when sending them, but it depends on the SMTP server to also support UTF-8 by 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

@

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

When searching for users in the Admin Console or by the User API, the count of users returned from the

/admin/realms/{realm}/users/count

/admin/realms/{realm}/users

If you are relying on the users count endpoint, make sure to review your clients so that they expect the users count to be aligned with the actual number of users returned from searches.

When adding an OTP, WebAuthn or any other 2FA credentials, the name the user assigns to this credential needs to be unique for the given user. This allows the user to distinguish between those credentials, and either update or delete them later. If a user tries to create a credential with an already existing name, there is an error message and the user is asked to change the name of the new credential.

To enhance security, only users with the

admin

master

Until now, the OpenID Connect broker did not support the standard

email_verified

In this release, the broker was updated to respect the value from this claim to set the email verification status for the federated (local) user account. Whenever users are federated for the first time or re-authenticating, if the

Trust email

Sync Mode

FORCE

In the future, we might evaluate changing this specific configuration to avoid automatic updates on the email verification status on federated user accounts depending on the use cases and the demand from the community.

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 First login flow.

Previously, when a user updated their credentials, like changing their password or adding another factor like an OTP or Passkey, they had a checkbox Sign out from other devices which was checked by default. Since this release, Red Hat build of Keycloak displays the checkbox Sign out from other devices not checked by default. This checkbox should now be intentionally enabled by the user to logout all the other related sessions associated to the same user.

Related to the previous point, in previous versions, the Sign out from other devices checkbox logged out only regular sessions. Starting with this release, it logs out also offline sessions as this is what users would expect to happen given the current screen design.

To revert to the old behavior, enable the deprecated feature

logout-all-sessions:v1

The Welcome Page creates regular Admin users instead of temporary ones.

The fine-grained admin permissions (FGAP) feature now includes a new scope:

reset-password

manage

By default, a user with the existing, broader

manage

USERS

reset-password

manage

manage

This implicit fallback mechanism ensures a smooth upgrade process for deployments already using fine-grained permissions. The fallback will be deprecated and removed in a future releases, so it is recommended to review and update administrator permissions to use the new

reset-password

For more details, see fine-grained admin permissions.

Until now, failures when searching for users from an LDAP user federation provider caused the whole request to fail and no users were returned. In this release, if an error occurs during the search, local users will still be returned and the error will be logged at the

ERROR

This change improves the resilience of the system when there are temporary issues with the LDAP server, ensuring that local users can still be accessed even if the LDAP search fails. If a local user is linked to a failing LDAP provider, the user will be marked as disabled and read-only until the LDAP server is available again.

Starting with this version, the

serverinfo

If, for whatever reason, an administrator in a common realm needs to access the

systemInfo

cpuInfo

memoryInfo

serverinfo

The previous workaround is marked as deprecated and it can be removed in a future version of Red Hat build of Keycloak.

The

SimpleHttp

server-spi-private

org.keycloak.http.simple

The

user-profile-commons.ftl

locale

When returning subgroups of a group, the count of subgroups of each subgroup of a group is no longer cached. With the introduction of Fine-Grained Admin Permissions, the result set is filtered at the database level based on any permissions defined to a realm so that the count will change accordingly to these permissions.

Instead of caching the count, a query will be executed every time to obtain the expected number of groups an administrator can access.

Most of the time, this change will not impact clients querying the API to fetch the subgroups of a group. However, if not the case, a new parameter

subGroupsCount

With this parameter, clients can decide whether the count should be returned to each individual group returned. To not break existing deployments, this parameter defaults to

true

Previously the default browser flow had a Browser - Conditional OTP conditional sub-flow that enabled One-Time Password (OTP) as a 2nd Factor Authentication (2FA). Starting with this version, the sub-flow is renamed to Browser - Conditional 2FA, the OTP Form is Alternative, and includes two more 2FA methods: WebAuthn Authenticator and Recovery Authentication Code Form. Both new executions are Disabled by default, but they can be set to Alternative to include them into the flow.

Upgraded realms will not be changed. The updated flow will only be available for new realms. Take this change into consideration if you have automated the realm creation.

Syslog messages sent over

tcp

ssl-tcp

To change this behavior, use the

--log-syslog-counting-framing

protocol-dependent

true

false

At version 26.4.1, 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

To change the threshold, set the

index-creation-threshold

connections-liquibase

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

You can disable this feature by setting it to zero or a negative number:

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

To enable manual upgrading of the database schema, set the

migration-strategy

connections-jpa

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

To change the path and name of the exported SQL file, set the

migration-export

connections-jpa

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

This comparison shows that the first change (

Hello world!!

if pageRedirectUri

In an alternative approach, the following screenshot compares the

info.ftl

info.ftl

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

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