Chapter 1. Red Hat build of Keycloak 24.0

In this release, changes to the User Profile SPI might impact existing implementations based on this SPI. For more details, see the Upgrading Guide.

In this release, the following templates were updated to make it possible to dynamically render attributes based on the user profile configuration set to a realm:

For more details, see the Upgrading Guide.

In this release, the server renders the update profile page when the user is authenticating through a broker for the first time using the idp-review-user-profile.ftl template.

For more details, see the Upgrading Guide.

This release contains support for Lightweight access tokens. As a result, you can have smaller access tokens for specified clients. These tokens have only a few claims, which is why they are smaller. Note that lightweight access token is still JWT signed by the realm key by default and still contains some very basic claims.

This release introduces an Add to lightweight access token flag that is available on some OIDC protocol mappers. Use this flag to specify if a particular claim should be added to a lightweight access token. It is OFF by default, which means that most claims are not added.

Also, a client policy executor exists. Use it to specify if a particular client request should use lightweight access tokens or regular access tokens. An alternative to the executor is to use an Always use lightweight access token flag on client advanced settings, which causes that client to always use lightweight access tokens. An executor can be an alternative if you need more flexibility. For instance, you may choose to use lightweight access tokens by default but use regular tokens only for the specified scope parameter.

In previous versions, introspection endpoint automatically returned most claims, which were available in the access token. Now most of protocol mappers include a new Add to token introspection switch . This addition allows more flexibility because an introspection endpoint can return different claims than an access token. This change is a first step towards "Lightweight access tokens" support because access tokens can omit lots of the claims, which would be still returned by the introspection endpoint. When migrating from previous versions, the introspection endpoint should return the same claims that are returned from access token, so the behavior should be effectively the same by default after the upgrade.

For more details, see Using lightweight access tokens.

This release contains optional OAuth 2.1 support. New client policy profiles were introduced in this release, which administrators can use to make sure that clients and particular client requests comply with the OAuth 2.1 specification. This release includes a dedicated client profile for confidential clients and a dedicated profile for public clients.

For more details, see OAuth 2.1 support.

Starting with this release, the scope parameter in the OAuth2/OIDC endpoint for token refresh is supported. Use this parameter to request access tokens with a smaller amount of scopes than originally granted, which means you cannot increase access token scope. This scope limitation does not affect the scope of the refreshed refresh token. This function works as described in the OAuth2 specification.

For more details, see the Server Administration Guide.

A new client policy executor secure-redirect-uris-enforcer is introduced. Use it to restrict which redirect URIs can be used by the clients. For instance, you can specify that client redirect URIs cannot have wildcards, should be just from specific domain, must be OAuth 2.1 compliant, and so on.

For more details, see Client Policies.

A new client policy executor dpop-bind-enforcer is introduced. You can use it to enforce DPoP for a particular client if dpop preview is enabled.

For more details, see Client Policies.

You can create EdDSA realm keys and use them as signature algorithms for various clients. For instance, you can use these keys to sign tokens or for client authentication with signed JWT. This feature includes identity brokering where Red Hat build of Keycloak itself signs client assertions that are used for private_key_jwt authentication to third party identity providers.

For more details, see Configuring Realm keys

The provider JavaKeystoreProvider for providing realm keys now supports EC keys in addition to previously supported RSA keys.

For more details, see Configuring Realm keys

OIDC identity providers now have the Add X.509 Headers to the JWT option for the situation when client authentication with JWT signed by private key is used. This option can be useful for interoperability with some identity providers such as Azure AD, which require the thumbprint to be present on the JWT.

For more details, see Integrating identity providers.

The Red Hat build of Keycloak codebase includes an internal update to introduce the OAuth Grant Type SPI. This update allows additional flexibility when introducing custom grant types supported by the Red Hat build of Keycloak OAuth 2 token endpoint.

For more details, see Authorization services.

Red Hat build of Keycloak has new client profiles fapi-2-security-profile and fapi-2-message-signing, which ensure Red Hat build of Keycloak enforces compliance with the latest FAPI 2 draft specifications when communicating with your clients.

For more details, see Client Policies.

Red Hat build of Keycloak has preview for support for OAuth 2.0 Demonstrating Proof-of-Possession at the Application Layer (DPoP).

The OAuth 2.0 device authorization grant flow now includes a feature flag, so you can easily disable this feature. This feature is still enabled by default.

For more details, see Device authorization grant.

Red Hat build of Keycloak has preview support for Passkeys.

Passkey registration and authentication are realized by the features of WebAuthn. Therefore, users of Red Hat build of Keycloak can do Passkey registration and authentication by existing WebAuthn registration and authentication.

Both synced Passkeys and device-bound Passkeys can be used for both Same-Device and Cross-Device Authentication. However, Passkeys operations success depends on the user’s environment. Make sure which operations can succeed in the environment.

WebAuthn policy includes a new field: Extra Origins. It provides better interoperability with non-Web platforms (for example, native mobile applications).

This release addresses an issue concerning when a user has a login page open in multiple browser tabs and is authenticated in one browser tab. When the user tried to authenticate in another browser tab, a message appeared: You are already logged-in. This situation is improved now as other browser tabs automatically authenticate the user after authentication in the first tab. However, more improvements are needed. For example, when an authentication session expires and is restarted in one browser tab, other browser tabs do not follow automatically with the login.

Red Hat build of Keycloak supports a new password policy that allows you to specify the maximum age of an authentication with which a password may be changed by a user without re-authentication. When this password policy is set to 0, the user is required to re-authenticate to change the password in the Account Console or by other means. You can also specify a lower or higher value than the default value of 5 minutes.

Red Hat build of Keycloak now features the http-max-queued-requests option to allow proper rejection of incoming requests under high load. For details, see the Server Guide.

Red Hat build of Keycloak has switched to RESTEasy Reactive. Applications using quarkus-resteasy-reactive should still benefit from a better startup time, runtime performance, and memory footprint, even though not using reactive style/semantics. SPIs that depend directly on JAX-RS API should be compatible with this change. SPIs that depend on RESTEasy Classic including ResteasyClientBuilder will not be compatible and will require an update. This update will also be needed for other implementation of the JAX-RS API like Jersey.

The Keycloak CR now includes an startOptimized field, which may be used to override the default assumption about whether to use the --optimized flag for the start command. As a result, you can use the CR to configure build time options also when a custom Keycloak image is used.

The Keycloak CR now allows for specifying the resources options for managing compute resources for the Keycloak container. It provides the ability to request and limit resources independently for the main Red Hat build of Keycloak deployment by using the Keycloak CR, and for the realm import Job by using the Realm Import CR.

When no values are specified, the default requests memory is set to 1700MiB, and the limits memory is set to 2GiB.

You can specify your custom values based on your requirements as follows:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  resources:
    requests:
      cpu: 1200m
      memory: 896Mi
    limits:
      cpu: 6
      memory: 3Gi

For more details, see the Operator Guide.

The Keycloak CR now allows for specifying the cache-config-file option by using the cache spec configMapFile field, for example:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ...
  cache:
    configMapFile:
      name: my-configmap
      key: config.xml

You may also take advantage of the new server-side handling of truststores by using the Keycloak CR, for example:

spec:
  truststores:
    mystore:
      secret:
        name: mystore-secret
    myotherstore:
      secret:
        name: myotherstore-secret

Currently only Secrets are supported.

The cert for the Kubernetes CA is added automatically to your Red Hat build of Keycloak Pods managed by the Operator.

The Red Hat build of Keycloak JS adapter now uses the exports field in its package.json. This change improves support for more modern bundlers like Webpack 5 and Vite, but comes with some unavoidable breaking changes. See the Upgrading Guide for more details.

The Red Hat build of Keycloak JS adapter now sets the pkceMethod option to S256 by default. This change enables Proof Key Code Exchange (PKCE) for all applications using the adapter. If you use the adapter on a system that does not support PKCE, you can set the pkceMethod option to false to disable it.

The SAML identity providers can now be configured to automatically download the signing certificates from the IDP entity metadata descriptor endpoint. In order to use the new feature, configure the Metadata descriptor URL option in the provider (the URL where the IDP metadata information with the certificates is published) and set Use metadata descriptor URL to ON. The certificates are automatically downloaded and cached in the public-key-storage SPI from that URL. The certificates can also be reloaded or imported from the Admin Console, using the action combo in the provider page.

See the Server Administration Guide for more details about the new options.

A new health check endpoint available at /lb-check was added. The execution is running in the event loop, which means this check is responsive also in overloaded situations when Red Hat build of Keycloak needs to handle many requests waiting in request queue. This behavior is useful, for example, in multi-site deployment to avoid failing over to another site that is under heavy load. The endpoint is currently checking availability of the embedded and external Infinispan caches. Other checks may be added later.

This endpoint is not available by default. To enable it, run Keyloak with the multi-site feature. For more details, see Enabling and disabling features.

In this release, we are encapsulating the root user attributes (such as username, email, firstName, lastName, and locale) by moving them to a base/abstract class in order to align how these attributes are marshalled and unmarshalled when using both Admin and Account REST APIs.

This strategy provides consistency in how attributes are managed by clients and makes sure they conform to the user profile configuration set to a realm.

For more details, see the Upgrading Guide.

When updating user attributes through the Admin User API, you cannot execute partial updates when updating the user attributes, including the root attributes such as username, email, firstName, and lastName.

For more details, see the Upgrading Guide.

Starting with this release, the first member of a Red Hat build of Keycloak cluster will load remote sessions sequentially instead of in parallel. If offline session preloading is enabled, those will be loaded sequentially as well.

For more details, see the Upgrading Guide.

In this release, you can no longer perform actions such as email verification if the user is already authenticated and the action is bound to another user. For instance, a user can not complete the verification email flow if the email link is bound to a different account.

In this release, if a user tries to follow the link to verify the email and the email was previously verified, a proper message will be shown.

In addition to that, a new error (EMAIL_ALREADY_VERIFIED) event will be fired to indicate an attempt to verify an already verified email. You can use this event to track possible attempts to hijack user accounts in case the link has leaked or to alert users if they do not recognize the action.

Message properties files for themes are now read in UTF-8 encoding, with an automatic fallback to ISO-8859-1 encoding.

See the Upgrading Guide for more details.

To reduce memory requirements, we introduced a configuration option to shorten lifespan for offline sessions imported into the Infinispan caches. Currently, the offline session lifespan override is disabled by default.

For more details, see the Server Administration Guide.

When enabling metrics for Red Hat build of Keycloak’s embedded caches, the metrics now use labels for the cache manager and the cache names.

For more details, see the Upgrading Guide.

As of this release, Red Hat build of Keycloak supports storing and searching by user attribute values longer than 255 characters, which was previously a limitation.

For more details, see the Upgrading Guide.

There have been a couple of enhancements to the Brute Protection:

In previous versions of Red Hat build of Keycloak, when the last member of a User, Group, or Client policy was deleted then that policy would also be deleted. Unfortunately this could lead to an escalation of privileges if the policy was used in an aggregate policy. To avoid privilege escalation, the effect policies are no longer deleted and an administrator will need to update those policies.

There is now a new event USER_DISABLED_BY_TEMPORARY_LOCKOUT when a user is temporarily locked out by the brute force protector. The log with ID KC-SERVICES0053 has been removed as the new event offers the information in a structured form.

For more details, see the Upgrading Guide.

Cookie handling code has been refactored and improved, including a new Cookie Provider. This provides better consistency for cookies handled by Red Hat build of Keycloak, and the ability to introduce configuration options around cookies if needed.

User Attribute Mapper For NameID allowed setting Name ID Format option to the following values:

However, Red Hat build of Keycloak does not support receiving AuthnRequest document with one of these NameIDPolicy, therefore these mappers would never be used. The supported options were updated to only include the following Name ID Formats:

Instead of specifying hardcoded values for the initial and maximum heap size, Red Hat build of Keycloak uses relative values to the total memory of a container. The JVM options -Xms and -Xmx were replaced by -XX:InitialRAMPercentage and -XX:MaxRAMPercentage.

For more details, see the Upgrading Guide.

The default behavior of Red Hat build of Keycloak is to load offline sessions on demand. The old behavior to preload them at startup is now deprecated, as pre-loading them at startup does not scale well with a growing number of sessions, and increases Red Hat build of Keycloak memory usage. The old behavior will be removed in a future release.

For more details, see the Upgrading Guide.