libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

User profile - release notes and more migration instructions (#27003)

Browse source 
closes #26917
closes #26932

Signed-off-by: mposolda <mposolda@gmail.com>


Co-authored-by: Pedro Igor <pigor.craveiro@gmail.com>
Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com>
This commit is contained in:
Marek Posolda 2024-02-15 08:14:16 +01:00 committed by GitHub
parent e2fb8406a3
commit 16fca0118e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 133 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

89
docs/documentation/release_notes/topics/24_0_0.adoc
View file

@ -1,3 +1,69 @@
= Supported user profile and progressive profiling
The user profile preview feature is promoted to be fully supported and user profile is enabled by default!
In the past months, Keycloak team spent a huge amount of effort in polishing the user
profile feature to make it fully supported. In this release, we continued the effort. Lots of improvements, fixes and
polishing were done based on the thorough testing and feedback from our awesome community.
Few highlights of the user profile feature:
* Fine-grained control over the attributes that users and administrators can manage so that you can prevent unexpected attributes, and values, from being set.
* Ability to specify what user attributes are managed and should be displayed on the forms to regular users or administrators
* Dynamic forms - Previously, the forms where users created or updated their profiles, contain four basic attributes like username, email, first name and last name. Any additional
attributes (or removing some of the default attributes) required to create custom theme. Now custom themes may no longer be needed because users see exactly the requested attributes based on the requirement
of the particular deployment
* Validations - Ability to specify validators for the user attributes including built-in validators that you can use to specify a maximum or minimum length, a specific regex, or limiting a
particular attribute to be a URL or number.
* Annotations - Ability to specify that particular attribute should be rendered for instance as text area or HTML select with specified options or calendar and lots of other options. You can also bind JavaScript code to a specific field to change how an attribute is rendered and customize its behavior.
* Progressive profiling - Ability to specify that some fields are required or available on the forms just for particular values of `scope` parameter. This effectively allow progressive
profiling. You no longer need to ask the user for twenty attributes during registration; you can instead ask the user to fill in attributes incrementally according to the requirements of the individual client
applications that are used by the user.
* Migration from previous versions - User profile is now always enabled, but it operates as before for those who did not use this feature previously. You can
benefit from the user profile capabilities, but you are not strictly forced to use them. For migration instructions consult the link:{upgradingguide_link}[{upgradingguide_name}].
This first release of the user profile as a supported feature is just the starting point and the baseline for delivering many more capabilities around identity management.
We would like to huge Thanks to awesome Keycloak community as lots of ideas, requirements and contributions came from the community! Special thanks to:
* https://github.com/velias[Vlastimil Eliáš]
* https://github.com/alechenninger[Alec Henninger]
* https://github.com/thomasdarimont[Thomas Darimont]
* https://github.com/bs-matil[Markus Till]
* https://github.com/sschu[Sebastian Schuster]
* https://github.com/antikalk[Oliver]
* https://github.com/patrickjennings[Patrick Jennings]
* https://github.com/adrhine[Andrew]
For more details about user profile capabilities, check link:{adminguide_link}#user-profile[{adminguide_name}].
== Breaking changes to the User Profile SPI
In this release, changes to the User Profile SPI might impact existing implementations based on this SPI. For more details, check the
link:{upgradingguide_link}[{upgradingguide_name}].
== 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`
For more details, see link:{upgradingguide_link}[{upgradingguide_name}].
== The update profile page when logging in for the first time through a broker now has its own Freemarker templates
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 link:{upgradingguide_link}[{upgradingguide_name}].
= Java adapter deprecation and removal
Back in 2022 we announced the https://www.keycloak.org/2022/02/adapter-deprecation.html[deprecation of Keycloak adapters in Keycloak 19].
@ -98,11 +164,6 @@ It is now possible to separately enable parsing of either `Forwarded` or `X-Forw
For details consult the https://www.keycloak.org/server/reverseproxy[Reverse Proxy Guide].
The original `--proxy` option is now deprecated and will be removed in a future release. For migration instructions consult the link:{upgradingguide_link}[{upgradingguide_name}].
= Breaking changes to the User Profile SPI
In this release, there are changes to the User Profile SPI that might impact existing implementations based on this SPI. For more details, check the
link:{upgradingguide_link}[{upgradingguide_name}].
= Changes to the user representation in both Admin API and Account contexts
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
@ -113,24 +174,6 @@ configuration set to a realm.
For more details, see link:{upgradingguide_link}[{upgradingguide_name}].
= 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`
For more details, see link:{upgradingguide_link}[{upgradingguide_name}].
= 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.
For more details, see link:{upgradingguide_link}[{upgradingguide_name}].
= 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.

116
docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc
View file

@ -50,6 +50,24 @@ If you need more predictable behavior across releases, reference the particular
= User Profile Changes
== User profile enabled by default
The user profile feature is now enabled by default. The `declarative-user-profile`feature is no longer available, because the user profile is assumed to be enabled.
Therefore, the *User Profile Enabled* switch is removed from the *Realm Settings* and replaced by *Unmanaged attributes*.
When migrating from previous version, the behavior is as follows:
* For the deployments where *User Profile Enabled* was set to *ON*, *Unmanaged attributes* will be set to *OFF* after the upgrade. As a result, only user attributes supported explicitly
by user profile will be allowed.
* For the deployments where the *User Profile Enabled* was set to *OFF* (which was also the default settings for the deployments with `declarative-user-profile` feature disabled, which was the default),
*Unmanaged attributes* will be set to *ON*` after the upgrade. As a result, the behavior should be basically the same as in previous versions with the user profile disabled.
The *Attributes* tab will remain in the user details part of the Admin Console. Also users can now set arbitrary attributes through UI pages such as the registration page and update profile page as long as
a particular custom theme supports it. The custom themes should work as before as well. However, consider updating your themes to use the user-profile (See below in the themes section) and
maybe even remove your custom themes if those themes were need to add custom attributes. We also recommend switching *Unmanaged attributes* to *OFF* or enable this switch only for
administrators so that you can rely on mainly on using managed attributes.
See the link:{adminguide_link}#user-profile[User Profile Documentation] for the details about the *Unmanaged attributes*.
== Default validations
Default user profile configuration comes with a set of default validations for the basic predefined fields. Those validations were not present in previous versions when the `declarative-user-profile` feature was disabled by default.
@ -78,6 +96,55 @@ attributes with such strange names in the user profile configuration. So you may
The required action `verify-profile` is enabled by default for new realms. But when you are migrating from previous version, your existing realms will have same state of this `verify-profile` action as before, which
usually means disabled as it was disabled by default in previous versions. For the details about this required action, see the link:{adminguide_link}#user-profile[User Profile Documentation].
== 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 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 for 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 expected 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 a previous release 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 has 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 the 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.
= 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].
@ -107,17 +174,6 @@ The `--proxy` option has been deprecated and will be removed in a future release
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
@ -136,44 +192,6 @@ this method is not available from the representation payload and it is targeted
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.