Chapter 2. Release-specific changes

The acr_values request parameter is no longer automatically forwarded to OpenID Connect identity providers during authentication. This change enhances security by preventing unintended disclosure of authentication context information to external IDPs.

If you are relying on the acr_values parameter to be propagated to an identity provider, you must now explicitly set acr_values request parameter to the Forwarded query parameters setting in the identity provider configuration.

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 and GROUP_ATTRIBUTE tables. If those tables contain 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. See the Upgrading Guide for details on how to configure a different limit.

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}) and searching for a user (GET /admin/realms/{realm}/users). When BruteForce is enabled and a user was temporarily locked out, the former endpoint would return enabled=false while the latter would return enabled=true. If the user was updated and enabled was false due to temporary lockout then the user would be disabled permanently. Both endpoints now return enabled=true when a user is temporarily locked out. To check whether a user is temporarily locked out the BruteForceUserResource endpoint should be utilised (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).

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/ folder from the old to the new installation. The new procedure recommends to re-apply any changes to cache-ispn.xml or a custom cache configuration based on the file included in the new version.

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

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 request parameter to false when invoking the /admin/realms/{realm}/users using the GET method.

For instance, searching for all users with the attribute myattribute set should be done as follows:

GET /admin/realms/{realm}/users?exact=false&q=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 request parameter.

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 property of the PostgreSQL JDBC driver to primary to ensure that it always connects to a writable primary instance and never connects to a secondary reader instance in failover or switchover scenarios.

You can override this behavior by setting your own value for targetServerType in the DB URL or additional properties.

The EVENT_ENTITY table now has an index IDX_EVENT_ENTITY_USER_ID_TYPE on the columns USER_ID, TYPE and EVENT_TIME, which allows a faster search in the Admin Console for events of a specific user and event type.

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 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, you no longer need 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 conf/cache-ispn.xml file no longer contains the default cache configurations. You can still overwrite the cache configurations used by Red Hat build of Keycloak in this file, however Red Hat build of Keycloak logs a warning if the --cache-config-mutate=true option is not set. You can still add custom caches without setting this option.

When upgrading an existing deployment, remove all default cache configurations from your existing conf/cache-ispn.xml and use the --cache-... options to make changes for example to the cache sizes.

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 setting.

Starting with this release, Red Hat build of Keycloak defines a default db-pool-max-lifetime of 7 hours and 50 minutes for MySQL and MariaDB databases as the default wait_timeout is 8 hours.

If the server defines a wait_timeout which is greater than the default, or provided, db-pool-max-lifetime value, then a warning will be logged on Red Hat build of Keycloak startup.

Red Hat build of Keycloak now exposes an RFC8414-compliant endpoint at the root URL level /.well-known/ to allow clients to discover OAuth 2.0 Authorization Server Metadata and other well-known providers by the issuer URL.

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

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}

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

To benefit from this, expose the path /.well-known/ in your reverse proxy configuration.

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.* and jgroups.external_* system properties. This release introduces the following CLI options to allow these addresses and ports to be configured directly by Red Hat build of Keycloak:

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 endpoint for an OAuth 2.0 IDP that provides refresh tokens and JSON responses or for OIDC IDPs, the tokens will be automatically refreshed each time they are retrieved via the endpoint if the access token has expired and the IDP provided a refresh 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, but users are encouraged to load test their environment to verify performance improvements.

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 and cache-embedded-offline-client-sessions-max-count options.

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 or pt-BR, a file is still named messages_de.properties or messages_pt_BR.properties. If you added custom language code, check if your file names are still the same.

The "Chinese (traditional)" and "Chinese (simplified)" languages are named for historical reasons zh-TW and zh-CN in the community themes of Red Hat build of Keycloak. As a start to migrate to the new language codes, zh-Hant and zh-Hans, the classloader and folder based themes pick up for the old language codes zh-TW and zh-CN and also the messages_zh_Hant.properties and messages_zh_Hant.properties files. Entries in messages_zh_Hant.properties take precedence over entries in messages_zh_TW.properties, and entries in messages_zh_Hans.properties take precedence over entries in messages_zh_CN.properties.

Update Email is now a supported feature so it is now enabled during the server startup. The feature is enabled for a realm if the Update Email required action is enabled in the realm. The feature slightly changes behavior from previous versions when updating the profile during the authentication flow (such as when running the UPDATE_PROFILE required action). If a user has an email set when updating the profile during the authentication flow, the email attribute is not available.

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 to false.

If no value is specified either on the LDAP configuration as the connectionTimeout or by the com.sun.jndi.ldap.connect.timeout system property, the default timeout is 5 seconds. This timeout ensures that requests will see errors rather than indefinite waits in obtaining an LDAP connection from the pool or when making a connection to the LDAP server.

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 parameter, which has maximum length of 255 characters. This value is aligned with the maximum length for the username and email attributes configured in the default user profile configuration.

If you want to increase or lower those numbers, start the server with the option req-params-default-max-size for the default maximum length of the standard OIDC/OAuth2 parameters or you can use something such as req-params-max-size for one specific parameter. For more details, see the login-protocol provider configuration under All provider configuration.

Starting with 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 Configuring email for a realm.

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 @) using punycode if non-ASCII characters are used, and will reject email addresses that use non-ASCII characters in the local part. The built-in User Profile email validator also checks that the local part of the address contains only ASCII characters when this option is disabled, avoiding the registration of emails that cannot be used by the SMTP configuration.

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 endpoint is now aligned with the actual number of users returned when executing searches by /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 role in the master realm (server admins) can assign admin roles. This ensures that critical permissions cannot be delegated by realm-level administrators.

Until now, the OpenID Connect broker did not support the standard email_verified claim available from the ID Tokens issued by OpenID Connect Providers.

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 setting is enabled and Sync Mode is set to FORCE, the user account will be updated to (un)mark the email as verified. If the provider does not send the claim, it defaults to the original behavior and sets the email as verified.

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. This deprecated feature will be removed in a future version.

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. This scope allows for specific permissions to be granted to administrators to reset a user’s password without granting them broader manage scope.

By default, a user with the existing, broader manage scope for the USERS resource type will implicitly have permission to reset a user’s password. The system checks for the explicit reset-password scope first. If that permission is not found, it falls back to checking if the administrator has the manage scope. This ensures that existing administrators with the manage scope continue to have the ability to reset passwords without any changes to their permissions.

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 scope where appropriate.

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 level, so that administrators can investigate the root cause of the problem and fix any issue with their LDAP configuration or connectivity with the LDAP server.

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 endpoint, which is used by the admin console to obtain some general information of the Red Hat build of Keycloak installation, will only return the system information for administrators in the administration (master) realm. This change was done for security reasons.

If, for whatever reason, an administrator in a common realm needs to access the systemInfo, cpuInfo or memoryInfo fields of the serverinfo response, you need to create and assign a new view-system role to that admin user:

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

The SimpleHttp util in the server-spi-private module was refactored and moved to the org.keycloak.http.simple package.

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

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 was introduced to the following endpoints:

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 so that the count is returned if the parameter is not set.

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 (or ssl-tcp) protocol now use counting framing by default, prefixing messages with their size as required by some Syslog servers.

To change this behavior, use the --log-syslog-counting-framing option with one of the following values: protocol-dependent (default), true, or 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.