From ab7426b85788647093bc129dc606139f4b7ed7df Mon Sep 17 00:00:00 2001 From: mposolda Date: Fri, 2 Feb 2024 11:27:59 +0100 Subject: [PATCH] User profile migration documentation for default validations and strange attributes closes #26634 closes #25979 Signed-off-by: mposolda Co-authored-by: andymunro <48995441+andymunro@users.noreply.github.com> --- .../topics/keycloak/changes-24_0_0.adoc | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) 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 acd47d512c..672be3dea5 100644 --- a/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc +++ b/docs/documentation/upgrading/topics/keycloak/changes-24_0_0.adoc @@ -48,6 +48,36 @@ It is no longer allowed to have the same feature in both the `--features` and `- 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`. += User Profile Changes + +== 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. +If you have issues due the backwards compatibility, you can change the default validators according to your needs. The default validators are as follows: + +* The`username`, `email`, `firstName` and `lastName` attributes have a maximum length of 255 characters. These validations were indirectly present in previous versions as well +due there is a database constraint on the table `USER_ENTITY` for those fields with a maximum length of 255 characters. However when using user storage providers, it might be possible before to use longer values. + +* The `username` attribute has a minimum length of three characters. Username has also `username-prohibited-characters` and `up-username-not-idn-homograph` validator by default, which were not present in previous versions. +See the link:{adminguide_link}#user-profile[Validation section of the User Profile Documentation] for the details about those attributes. Note that username is not editable by default unless you have the realm switch `Edit username enabled`. +This change means that existing users with incorrect usernames should still work and they will not be enforced to update their usernames. But new users will be enforced to use correct usernames +during their registration or creation by the admin REST API. + +* Attributes `firstName` and `lastName` have the `person-name-prohibited-characters` validator on them, which were not present in previous versions. +See the link:{adminguide_link}#user-profile[Validation section of the User Profile Documentation] for the details about those attributes. Note that both first +name and last name are editable by default, so users, who already have such incorrect first/last name from a previous version will be forced to update them when updating their user profiles. + +== User attribute names with strange characters + +In previous versions, it was possible to create a user with attribute names like `some:attribute` or `some/attribute`. User profile intentionally does not allow you to create +attributes with such strange names in the user profile configuration. So you may need to configure `Unmanaged attributes` for your realm and enable unmanaged attributes for administrators +(ideally) or for end users (if really needed). Although it is strongly preferred to avoid using such attribute names. + +== Verify Profile required action enabled by default + +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]. + = 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].