From 16fca0118e1c49a42338730c4cc59816005ee14f Mon Sep 17 00:00:00 2001 From: Marek Posolda Date: Thu, 15 Feb 2024 08:14:16 +0100 Subject: [PATCH] User profile - release notes and more migration instructions (#27003) closes #26917 closes #26932 Signed-off-by: mposolda Co-authored-by: Pedro Igor Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> --- .../release_notes/topics/24_0_0.adoc | 89 ++++++++++---- .../topics/keycloak/changes-24_0_0.adoc | 116 ++++++++++-------- 2 files changed, 133 insertions(+), 72 deletions(-) diff --git a/docs/documentation/release_notes/topics/24_0_0.adoc b/docs/documentation/release_notes/topics/24_0_0.adoc index 3ad5763ce7..b77ecf6baf 100644 --- a/docs/documentation/release_notes/topics/24_0_0.adoc +++ b/docs/documentation/release_notes/topics/24_0_0.adoc @@ -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. diff --git a/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc b/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc index d0efbc02b6..4c708d2bfa 100644 --- a/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc +++ b/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc @@ -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.