314 lines
18 KiB
Text
314 lines
18 KiB
Text
= Changes to the Welcome theme
|
|
|
|
The 'welcome' theme has has been updated to use a new layout and now uses PatternFly 5, rather than PatternFly 3. If you are extending the theme, or providing your own, you may need to update it as follows:
|
|
|
|
== Migrate from PatternFly 3 to PatternFly 5
|
|
|
|
The welcome theme was one of the more outdated themes in Keycloak. It was originally based on PatternFly 3, but has now been updated to use PatternFly 5, skipping a major version in the process. This means that if your custom theme extends the built-in theme you will need to update it to use PatternFly 5 syntax. Consult the https://www.patternfly.org/get-started/develop/[PatternFly 5 documentation] for details.
|
|
|
|
If you are still using PatternFly 3 in your own custom theme (not extending the built-in one), you can continue to use it, but PatternFly 3 support will be removed in a future release, so you should consider migrating to PatternFly 5 as soon as possible.
|
|
|
|
== Automatic redirect to the Administration Console
|
|
|
|
If the Administration Console is enabled, the welcome page will automatically redirect to it if the administrative user already exists. This behavior can be modified by setting the `redirectToAdmin` in your `theme.properties` file. By default, the property is set to `false`, unless you are extending the built-in theme, in which case, the property is set to `true`.
|
|
|
|
== The `documentationUrl` and `displayCommunityLinks` properties have been removed.
|
|
|
|
These properties were previously used for navigational elements that are now no longer present. If you are extending the built-in theme, you will need to remove these properties from your `theme.properties` file, as they no longer have any effect.
|
|
|
|
== Assets are now loaded from 'common' resources
|
|
|
|
Images such as the background, logo and favicon are now loaded from the 'common' resources, rather than the theme resources. This change means that if you are extending the built-in theme, and are overwriting these images, you will need to move them to the 'common' resources of your theme, and update your `theme.properties` file to include the new paths:
|
|
|
|
[source,properties]
|
|
----
|
|
# This defaults to 'common/keycloak' if not set.
|
|
import=common/your-theme-name
|
|
----
|
|
|
|
= Keycloak JS imports might need to be updated
|
|
|
|
If you are loading Keycloak JS directly from the Keycloak server, this section can be safely ignored. If you are loading Keycloak JS from the NPM package and are using a bundler like Webpack, Vite, and so on, you might need to make some changes to your code. The Keycloak JS package now uses the https://webpack.js.org/guides/package-exports/[`exports` field] in the package.json file. This means that you might have to change your imports:
|
|
|
|
[source,js]
|
|
----
|
|
// Before
|
|
import Keycloak from 'keycloak-js/dist/keycloak.js';
|
|
import AuthZ from 'keycloak-js/dist/keycloak-authz.js';
|
|
|
|
// After
|
|
import Keycloak from 'keycloak-js';
|
|
import AuthZ from 'keycloak-js/authz';
|
|
----
|
|
|
|
= Features Changes
|
|
|
|
It is no longer allowed to have the same feature in both the `--features` and `--features-disabled` list. The feature should appear in only one list.
|
|
|
|
The usage of unversioned feature names, e.g. `docker`, in the `--features` list will allow for the most supported / latest feature version to be enabled for you.
|
|
If you need more predictable behavior across releases, reference the particular version you want instead, e.g. `docker:v1`.
|
|
|
|
= Truststore Changes
|
|
|
|
The `spi-truststore-file-*` options and the truststore related options `https-trust-store-*` are deprecated, please use the new default location for truststore material, `conf/truststores`, or specify your desired paths via the `truststore-paths` option. For details refer to the relevant https://www.keycloak.org/server/keycloak-truststore[guide].
|
|
|
|
The `tls-hostname-verifier` property should be used instead of the `spi-truststore-file-hostname-verification-policy` property.
|
|
|
|
= Deprecated `--proxy` option
|
|
|
|
The `--proxy` option has been deprecated and will be removed in a future release. The following table explains how the deprecated option maps to supported options.
|
|
|
|
[%autowidth,cols="a,a"]
|
|
|===
|
|
| Deprecated usage | New usage
|
|
|
|
|`kc.sh` (no `proxy` option set)
|
|
|`kc.sh`
|
|
|`kc.sh --proxy none`
|
|
|`kc.sh`
|
|
|`kc.sh --proxy edge`
|
|
|`kc.sh --proxy-headers forwarded\|xforwarded --http-enabled true`
|
|
|`kc.sh --proxy passthrough`
|
|
|`kc.sh --hostname-port 80\|443` (depending if HTTPS is used)
|
|
|`kc.sh --proxy reencrypt`
|
|
|`kc.sh --proxy-headers forwarded\|xforwarded`
|
|
|===
|
|
|
|
NOTE: For hardened security, the `--proxy-headers` option does not allow selecting both `forwarded` and `xforwarded` values at the same time (as it was
|
|
the case before for `--proxy edge` and `--proxy reencrypt`).
|
|
|
|
= Breaking changes to the User Profile SPI
|
|
|
|
If you are using the User Profile SPI in your extension, you might be impacted by the API changes introduced in this release.
|
|
|
|
The `org.keycloak.userprofile.Attributes` interface includes the following changes:
|
|
|
|
* Method `getValues` was renamed to `get` to make it more aligned with the same operation from a regular Java `Map`
|
|
* Method `isRootAttribute` was moved to the utility class `org.keycloak.userprofile.UserProfileUtil.isRootAttribute`
|
|
* Method `getFirstValue` was renamed to `getFirst` to make it less verbose
|
|
* Method `getReadable(boolean)` was removed and now all attributes (including root attributes) are returned whenever they have read rights.
|
|
|
|
= Changes to the user representation in both Admin API and Account contexts
|
|
|
|
Both `org.keycloak.representations.idm.UserRepresentation` and `org.keycloak.representations.account.UserRepresentation` representation classes have changed
|
|
so that the root user attributes (such as `username`, `email`, `firstName`, `lastName`, and `locale`) have a consistent representation when fetching or sending
|
|
the representation payload to the Admin and Account APIS, respectively.
|
|
|
|
The `username`, `email`, `firstName`, `lastName`, and `locale` attributes were moved to a new `org.keycloak.representations.idm.AbstractUserRepresentation` base class.
|
|
|
|
Also the `getAttributes` method is targeted for representing only custom attributes, so you should not expect any root attribute in the map returned by this method. This method is
|
|
mainly targeted for clients when updating or fetching any custom attribute for a give user.
|
|
|
|
In order to resolve all the attributes including the root attributes, a new `getRawAttributes` method was added so that the resulting map also includes the root attributes. However,
|
|
this method is not available from the representation payload and it is targeted to be used by the server when managing user profiles.
|
|
|
|
= `https-client-auth` is a build time option
|
|
|
|
Option `https-client-auth` had been treated as a run time option, however this is not supported by Quarkus. The option needs to be handled at build time instead.
|
|
|
|
= Changes to Freemarker templates to allow rendering pages based on the user profile configuration set to a realm
|
|
|
|
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:
|
|
|
|
* `login-update-profile.ftl`
|
|
* `register.ftl`
|
|
* `update-email.ftl`
|
|
|
|
These templates are responsible for rendering the update profile (when the `Update Profile` required action is enabled to a user),
|
|
the registration, and the update email (when the `UPDATE_EMAIL` feature is enabled) pages, respectively.
|
|
|
|
If you use a custom theme to change these templates, they will function as expect because only the content is updated.
|
|
However, we recommend you to take a look at how to configure a link:{adminguide_link}#user-profile[{declarative user profile}] and possibly avoid
|
|
changing the built-in templates by using all the capabilities provided by this feature.
|
|
|
|
Also, the templates used by the `declarative-user-profile` feature to render the pages for the same flows are longer necessary and removed in this release:
|
|
|
|
* `update-user-profile.ftl`
|
|
* `register-user-profile.ftl`
|
|
|
|
If you were using the `declarative-user-profile` feature in previously releases with customizations to the above templates,
|
|
update the `login-update-profile.ftl` and `register.ftl` accordingly.
|
|
|
|
= The update profile page when logging in for the first time through a broker now have its own Freemarker templates
|
|
|
|
In this release, the server will render the update profile page when the user is authenticating through a broker for the
|
|
first time using the `idp-review-user-profile.ftl` template.
|
|
|
|
In previous releases, the template used to update the profile during the first broker login flow was the `login-update-profile.ftl`, the same used
|
|
to update profile when users are authenticating to a realm.
|
|
|
|
By using separate templates for each flow, a more clear distinction exist as to which flow a template is actually used rather than sharing a same template,
|
|
and potentially introduce unexpected changes and behavior that should only affect pages for a specific flow.
|
|
|
|
If you have customizations to the `login-update-profile.ftl` template to customize how users update their profiles when authenticating through a broker, make sure to move your changes
|
|
to the new template.
|
|
|
|
= Sequential loading of offline sessions and remote sessions
|
|
|
|
Starting with this release, the first member of a Keycloak cluster will load remote sessions sequentially instead of in parallel.
|
|
If offline session preloading is enabled, those will be loaded sequentially as well.
|
|
|
|
The previous code led to high resource-consumption across the cluster at startup and was challenging to analyze in production environments and could lead to complex failure scenarios if a node was restarted during loading.
|
|
Therefore, it was changed to sequential session loading.
|
|
|
|
For offline sessions, the default in this and previous versions of Keycloak is to load those sessions on demand, which scales better with a lot of offline sessions than the attempt to preload them in parallel. Setups that use this default setup are not affected by the change of the loading strategy for offline sessions.
|
|
Setups that have offline session preloading enabled should migrate to a setup where offline-session preloading is disabled.
|
|
|
|
= Deprecated offline session preloading
|
|
|
|
The default behavior of Keycloak is to load offline sessions on demand.
|
|
The old behavior to preload them at startup is now deprecated, as preloading them at startup does not scale well with a growing number of sessions, and increases Keycloak memory usage.
|
|
The old behavior will be removed in a future release.
|
|
|
|
To re-enable old behavior while it is deprecated and not removed yet, use the feature flag and the SPI option as shown below:
|
|
|
|
[source,bash]
|
|
----
|
|
bin/kc.[sh|bat] start --features-enabled offline-session-preloading --spi-user-sessions-infinispan-preload-offline-sessions-from-database=true
|
|
----
|
|
|
|
The API of `UserSessionProvider` deprecated the method `getOfflineUserSessionByBrokerSessionId(RealmModel realm, String brokerSessionId)`.
|
|
Instead of this method, use `getOfflineUserSessionByBrokerUserIdStream(RealmModel, String brokerUserId)` to first get the sessions of a user, and then filter by the broker session ID as needed.
|
|
|
|
= Infinispan metrics use labels for cache manager and cache names
|
|
|
|
When enabling metrics for {project_name}'s embedded caches, the metrics now use labels for the cache manager and the cache names.
|
|
|
|
.Old metric example without labels
|
|
----
|
|
vendor_cache_manager_keycloak_cache_sessions_statistics_approximate_entries_in_memory{cache="sessions",node="..."}
|
|
----
|
|
|
|
.New metric example with labels
|
|
----
|
|
vendor_statistics_approximate_entries_in_memory{cache="sessions",cache_manager="keycloak",node="..."}
|
|
----
|
|
|
|
To revert the change for an installation, use a custom Infinispan XML configuration and change the configuration as follows:
|
|
|
|
----
|
|
<metrics names-as-tags="false" />
|
|
----
|
|
|
|
= The Admin send-verify-email API now uses the same email verification template
|
|
|
|
----
|
|
PUT /admin/realms/{realm}/users/{id}/send-verify-email
|
|
----
|
|
|
|
In this release, the API will use the `email-verification.ftl` template instead of `executeActions.ftl`.
|
|
|
|
.Before upgrading
|
|
----
|
|
Perform the following action(s): Verify Email
|
|
----
|
|
|
|
.After upgrading
|
|
----
|
|
Confirm validity of e-mail address email@example.org.
|
|
----
|
|
|
|
If you have customized the `executeActions.ftl` template to modify how users verify their email using this API, ensure that you transfer your modifications to the new template.
|
|
|
|
A new parameter called `lifespan` will be introduced to allow overriding of the default lifespan value (12 hours).
|
|
|
|
If you prefer the previous behavior, use the `execute-actions-email` API as follows.
|
|
|
|
----
|
|
PUT /admin/realms/{realm}/users/{id}/execute-actions-email
|
|
|
|
["VERIFY_EMAIL"]
|
|
----
|
|
|
|
= Removal of the deprecated mode for SAML encryption
|
|
|
|
The compatibility mode for SAML encryption introduced in version 21 is now removed. The system property `keycloak.saml.deprecated.encryption` is not managed anymore by the server. The clients which still used the old signing key for encryption should update it from the new IDP configuration metadata.
|
|
|
|
= Changes to Password Hashing
|
|
|
|
In this release we adapted the password hashing defaults to match the https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html#pbkdf2[OWASP recommendations for Password Storage].
|
|
|
|
As part of this change, the default password hashing provider has changed from `pbkdf2-sha256` to `pbkdf2-sha512`.
|
|
Also, the number of default hash iterations for `pbkdf2` based password hashing algorithms changed as follows:
|
|
[%autowidth,cols="a,a,>a,>a"]
|
|
|===
|
|
| Provider ID | Algorithm | Old Iterations | New Iterations
|
|
|
|
| `pbkdf2` | `PBKDF2WithHmacSHA1` | 20.000 | 1.300.000
|
|
| `pbkdf2-sha256` | `PBKDF2WithHmacSHA256` | 27.500 | 600.000
|
|
| `pbkdf2-sha512` | `PBKDF2WithHmacSHA512` | 30.000 | 210.000
|
|
|===
|
|
|
|
If a realm does not explicitly configure a password policy with `hashAlgorithm` and `hashIterations`, then
|
|
the new configuration will take effect on the next password based login, or when a user password is created or updated.
|
|
|
|
== Performance of new password hashing configuration
|
|
|
|
Tests on a machine with an Intel i9-8950HK CPU (12) @ 4.800GHz yielded the following ⌀ time differences for hashing 1000 passwords (averages from 3 runs).
|
|
Note that the average duration for the `PBKDF2WithHmacSHA1` was computed with a lower number of passwords due to the long runtime.
|
|
[%autowidth,cols="a,a,>a,>a,>a"]
|
|
|===
|
|
| Provider ID | Algorithm | Old duration | New duration | Difference
|
|
|
|
| `pbkdf2` | `PBKDF2WithHmacSHA1` | 122ms | 3.114ms | +2.992ms
|
|
| `pbkdf2-sha256` | `PBKDF2WithHmacSHA256` | 20ms | 451ms | +431ms
|
|
| `pbkdf2-sha512` | `PBKDF2WithHmacSHA512` | 33ms | 224ms | +191ms
|
|
|===
|
|
|
|
Users of the `pbkdf2` provider might need to explicitly reduce the
|
|
number of hash iterations to regain acceptable performance.
|
|
This can be done by configuring the hash iterations explicitly in the password policy of the realm.
|
|
|
|
== Expected increased overall CPU usage and temporary increased database activity
|
|
|
|
The Concepts for sizing CPU and memory resources in the Keycloak High Availability guide have been updated to reflect the new hashing defaults.
|
|
While the CPU usage per password-based login in our tests increased by 33% (which includes both the changed password hashing and unchanged TLS connection handling), the overall CPU increase should be around 10% to 15%.
|
|
This is due to the averaging effect of Keycloak's other activities like refreshing access tokens and client credential grants, still this depends on the unique workload of an installation.
|
|
|
|
After the upgrade, during a password-based login, the user's passwords will be re-hashed with the new hash algorithm and hash iterations as a one-off activity and updated in the database.
|
|
As this clears the user from Keycloak's internal cache, you'll also see an increased read activity on the database level.
|
|
This increased database activity will decrease over time as more and more user's passwords have been re-hashed.
|
|
|
|
== How to keep using the old pbkdf2-sha256 password hashing?
|
|
|
|
To keep the old password hashing for a realm, specify `hashAlgorithm` and `hashIterations` explicitly in the
|
|
realm password policy.
|
|
|
|
* `Hashing Algorithm: pbkdf2-sha256`
|
|
* `Hashing Iterations: 27500`
|
|
|
|
= Operator Referenced Resource Polling
|
|
|
|
Secrets and ConfigMaps referenced via the Keycloak CR will now be polled for changes, rather than watched via the api server. It may take around 1 minute for changes to be detected.
|
|
|
|
This was done so to not require label manipulation on those resources. After upgrading if any Secret still has the operator.keycloak.org/component label, it may be removed or ignored.
|
|
|
|
= Renaming JPA provider configuration options for migration
|
|
|
|
After removal of the Map Store the following configuration options were renamed:
|
|
|
|
* `spi-connections-jpa-legacy-initialize-empty` to `spi-connections-jpa-quarkus-initialize-empty`
|
|
* `spi-connections-jpa-legacy-migration-export` to `spi-connections-jpa-quarkus-migration-export`
|
|
* `spi-connections-jpa-legacy-migration-strategy` to `spi-connections-jpa-quarkus-migration-strategy`
|
|
|
|
= Renaming model modules
|
|
|
|
After removal of the Map Store the following modules were renamed:
|
|
|
|
* `org.keycloak:keycloak-model-legacy-private` to `org.keycloak:keycloak-model-storage-private`
|
|
* `org.keycloak:keycloak-model-legacy-services` to `org.keycloak:keycloak-model-storage-services`
|
|
|
|
and `org.keycloak:keycloak-model-legacy` module was deprecated and will be removed in the next release in favour of `org.keycloak:keycloak-model-storage` module.
|
|
|
|
= Updates to cookies
|
|
|
|
As part of refactoring cookie handling in Keycloak there are some changes to how cookies are set:
|
|
|
|
* All cookies will now have the secure attribute set if the request is through a secure context
|
|
* KEYCLOAK_LOCALE and WELCOME_STATE_CHECKER cookies now set SameSite=Strict
|
|
|
|
For custom extensions there may be some changes needed:
|
|
|
|
* LocaleSelectorProvider.KEYCLOAK_LOCALE is deprecated as cookies are now managed through the CookieProvider
|
|
* HttpResponse.setWriteCookiesOnTransactionComplete has been removed
|