Keycloak 18.0.0 released

April 20 2022

To download the release go to Keycloak downloads.

Release notes

New Operator preview

With this release, we’re introducing a brand new Keycloak Operator as a preview. Apart from being rewritten from scratch, the main user-facing change from the legacy Operator is the used Keycloak distribution – the new Operator uses the Quarkus distribution of Keycloak. With that, the API (in form of Custom Resource Definitions) has changed. For details, incl. installation and migration instructions, see the Operator related guides.

The legacy Operator will receive updates until Keycloak 20 when the Keycloak WildFly distribution reaches EOL.

OperatorHub versioning scheme

To avoid version conflicts with the legacy Operator, the 18.0.0 version of the new Operator is released as version 20.0.0-alpha.1 on OperatorHub. The legacy Operator versioning scheme remains the same, i.e. it is released as 18.0.0.

The same pattern will apply for future Keycloak 18 and 19 releases, until version 20 where the legacy Operator reaches EOL.

New Admin Console preview

The new Admin Console is now graduated to preview, with the plan for it to become the default admin console in Keycloak 19.

If you find any issues with the new console, or have some suggestions for improvements, please let us know through GitHub Discussions.

Step-up authentication

Keycloak now supports Step-up authentication. This feature was added in Keycloak 17, and was further polished in this version.

For more details, see Server Administration Guide.

Thanks to Cornelia Lahnsteiner and Georg Romstorfer for the contribution.

Client secret rotation

Keycloak now supports Client Secret Rotation through customer policies. This feature is now available as a preview feature and allows that confidential clients can be provided with realm policies allowing the use up to two secrets simultaneously.

For more details, see Server Administration Guide.

Recovery Codes

Recovery Codes as another way to do two-factor authentication is now available as a preview feature.

OpenID Connect Logout Improvements

Some fixes and improvements were made to make sure that Keycloak is now fully compliant with all the OpenID Connect logout specifications:

  • OpenID Connect RP-Initiated Logout 1.0

  • OpenID Connect Front-Channel Logout 1.0

  • OpenID Connect Back-Channel Logout 1.0

  • OpenID Connect Session Management 1.0

For more details, see Server Administration Guide.

WebAuthn improvements

Keycloak now supports WebAuthn id-less authentication. This feature allows that WebAuthn Security Key will identify the user during authentication as long as the security key supports Resident Keys. For more details, see Server Administration Guide. Thanks to Joaquim Fellmann for the contribution.

There are more WebAuthn improvements and fixes in addition to that.

The deprecated upload-script feature was removed

The upload-script feature has been marked as deprecated for a very long time. In this release, it was completely removed, and it is no longer supported.

If you are using any of these capabilities:

  • OpenID Connect Script Mapper

  • Script Authenticator (Authentication Execution)

  • JavaScript Policies

You should consider reading this documentation in order to understand how to still rely on these capabilities but deploying your scripts to the server rather than managing them through the management interfaces.

Session limits

Keycloak now supports limits on the number of sessions a user can have. Limits can be placed at the realm level or at the client level.

For more details, see Server Administration Guide. Thanks to Mauro de Wit for the contribution.

SAML ECP Profile is disabled by default

To mitigate the risk of abusing SAML ECP Profile, Keycloak now blocks this flow for all SAML clients that do not allow it explicitly. The profile can be enabled using Allow ECP Flow flag within client configuration, see Server Administration Guide.

Quarkus distribution

Import realms at startup

The Keycloak Quarkus distribution now supports importing your realms directly at start-up. For more information, check the corresponding guide.

JSON and File Logging improvements

The Keycloak Quarkus distribution now initially supports logging to a File and logging structured data using JSON.

For more information on the improvements, check the corresponding guide.

Environment variable expansion for values in keycloak.conf

The Keycloak Quarkus distribution now supports expanding values in keycloak.conf from environment variables.

For more information, check the corresponding guide.

New Option db-url-port

You can now change the port of your jdbc connection string explicitly by setting the new db-url-port configuration option. As for the other convenience options, this option will be overridden by the value of a full db-url, if set.

Split metrics-enabled option into health-enabled and metrics-enabled

The metrics-enabled option now only enables the metrics for Keycloak. To enable the readiness and liveness probe, there’s the new build option health-enabled. This allows more fine-grained usage of these options.

Other improvements

  • Account console alignments with latest PatternFly release.

  • Support for encrypted User Info endpoint response. Thanks to Giacomo Altiero

  • Support for the algorithm RSA-OAEP with A256GCM used for encryption keys. Thanks to Filipe Bojikian Rissi

  • Support for login with GitHub Enterprise server. Thanks to Neon Ngo

Migration from 17.0

Before you upgrade remember to backup your database. If you are not on the previous release refer to the documentation for a complete list of migration changes.

Step-up authentication

Step-up authentication is a new feature. This feature provides the acr client scope, which contains a protocol mapper that is supposed to add the acr claim in the token. The acr claim is not added automatically now as it was before this version, but it is added with the usage of this client scope and protocol mapper.

The client scope is added as a realm "default" client scope and hence will be added to all newly created clients. For performance reasons, the client scope is not automatically added to all existing clients during migration. The clients will not have an acr claim by default after the migration. Consider these possible actions:

  • If you do not plan to use step-up authentication feature, but you rely on the acr claim in the token, you can disable step_up_authentication feature as described in the Server Installation and Configuration Guide. The claim will be added with the value 1 in case of normal authentication and 0 in case of SSO authentication.

  • Add acr client scope to your clients manually by admin REST API or admin console. This is needed especially if you want to use step-up authentication. If you have a large number of clients in the realm and want to use acr claim for all of them, you can trigger some SQL similar to this against your DB. However, remember to clear the cache or restart the server if Keycloak is already started:

insert into CLIENT_SCOPE_CLIENT (CLIENT_ID, SCOPE_ID, DEFAULT_SCOPE) select CLIENT.ID as CLIENT_ID, CLIENT_SCOPE.ID as SCOPE_ID, true as DEFAULT_SCOPE
from CLIENT_SCOPE, CLIENT where CLIENT_SCOPE.REALM_ID='test' and CLIENT_SCOPE.NAME='acr' and CLIENT.REALM_ID='test' and CLIENT.PROTOCOL='openid-connect';

OpenID Connect Logout

Previous versions 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. While that implementation was easy to use, it had potentially negative impact on performance and security. The new version has better support for logout based on the OpenID Connect RP-Initiated Logout specification. The parameter redirect_uri is no longer supported; also, in the new version, the user needs to confirm the logout. It is possible to omit the confirmation and do automatic redirect to the application when you include parameter post_logout_redirect_uri together with the parameter id_token_hint with the ID Token used for login.

The existing deployments are affected in the following ways:

  • If your application directly uses links to logout endpoint with the redirect_uri parameter, you may be required to change this as described above. Consider either removing the redirect_uri parameter entirely or replacing it with the id_token_hint and post_logout_redirect_uri parameters.

  • If you use java adapters and your application does logout by call httpServletRequest.logout(), you are not affected because this call uses the backchannel variant of the logout endpoint and that one was not changed.

  • If you use the latest javascript adapter, you are also not affected. However if your application uses an older version of the JavaScript adapter, you are affected as this adapter uses the variant of the logout endpoint with the deprecated redirect_uri parameter. In this case, you may need to upgrade to the latest version of the JavaScript adapter.

  • For the Node.js adapter, the same guideline applies as for the JavaScript adapter. You are encouraged to update to the latest version as the older version of the adapter uses the deprecated redirect_uri parameter. With the latest Node.js adapter, you are not affected as long as you use the logout based on the /logout URL as described in the documentation or in the Node.js adapter example. However, in the case when your application directly uses the method keycloak.logoutUrl, you can consider adding idTokenHint as the second argument to this method. The possibility to add idTokenHint as second argument was newly added in this version. The idTokenHint needs to be a valid ID Token that was obtained during the login. Adding idTokenHint is optional, but if you omit it, your users will need to confirm the logout screen as described earlier. Also they will not be redirected back to the application after logout.

There is a backwards compatibility option, which allows your application to still use the old format of the redirect_uri parameter.

You can enable this parameter when you start the server by entering the following command:

bin/kc.[sh|bat] --spi-login-protocol-openid-connect-legacy-logout-redirect-uri=true start

With this configuration, you can still use the format with the redirect_uri parameter. Note the confirmation screen will be needed if the id_token_hint is omitted.

Warning
The backwards compatibility switch will be removed in some future version - probably Keycloak 21. You are encouraged to update your clients as soon as possible as described above rather than rely on this switch.

Removal of the upload-scripts feature

Previous versions of Keycloak had supported managing JavaScript code through the management interfaces like the administrations console and REST API. Starting from this version this is no longer possible, and you should now deploy your scripts to the server in order to configure the following providers:

  • OpenID Connect Script Mapper

  • Script Authenticator (Authentication Execution)

  • JavaScript Policies

More details about how to deploy scripts to the server are available in the documentation. Note that to use scripts, you are still required to enable the scripts technology preview feature.

kc.[sh|bat] start --auto-build --features=preview

When deploying scripts, the server is going to automatically create their corresponding providers so that you can select them when configuring authentication flows, mappers, and authorization policies.

In general, the steps to update your realms are the following:

  • Before upgrading, remove any script provider you are using.

  • After the upgrade, deploy your scripts following the instructions in the documentation.

  • Update your authentication flows, mappers, and the client authorization settings to use the providers created from the scripts deployed to the server.

Account console Patternfly upgrade

The Patternfly (PF) React libraries have been updated updated, @patternfly/react-core from v3.153.3 to v4.147.0, @patternfly/react-icons from v3.15.16 to v 4.11.8, and @patternfly/react-styles from v3.7.14 to v4.11.8. Several minor UI updates were made to bring the account console into alignment with PF design standards.

Custom developed account UIs might not be compatible with these updates due to the breaking changes in PF. Most breaking changes should be resovlable by updating props on PF components.

Resources:

Components known to have breaking changes:

  • Alert

  • action prop changed to actionClose

  • Expandable

  • renamed to ExpandableSection

  • Title

  • size attr now uses TitleSizes

  • DataListContent

  • noPadding changed to hasNoPadding

  • Grid, Stack, Level, Gallery

  • gutter attr changed to hasGutter

  • Modal

  • sizing control changed from, e.g. isLarge, to use ModalVariant, e.g. variant={ModalVariant.large}

  • Select

  • ariaLabelTypeAhead to typeAheadAriaLabel

  • isExpanded to isOpen

  • ariaLabelledBy to aria-labelledby

  • DataListContent

  • noPadding to hasNoPadding

Quarkus distribution: Split metrics-enabled option into health-enabled and metrics-enabled

The metrics-enabled option now only enables the metrics for Keycloak. To enable the readiness and liveness health endpoints, there’s a new boolean option health-enabled. This allows more fine-grained usage of these options, e.g. enabling metrics but not enabling readiness/liveness probes for on-premise use cases. In order to keep the same behaviour as before when metrics-enabled=true was set, you need to additionally set health-enabled=true when building Keycloak.

All resolved issues

New features

Enhancements

Bugs

Upgrading

Before you upgrade remember to backup your database and check the upgrade guide for anything that may have changed.