667ce4be9e
also adding a common PropertyMapper validation method closes #24668 Co-authored-by: Václav Muzikář <vaclav@muzikari.cz> Co-authored-by: Martin Bartoš <mabartos@redhat.com>
117 lines
No EOL
6.8 KiB
Text
117 lines
No EOL
6.8 KiB
Text
= 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, etc. 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. |