Reviewing the user profile documentation
Closes #26154 Signed-off-by: Pedro Igor <pigor.craveiro@gmail.com>
This commit is contained in:
Pedro Igor
Marek Posolda
parent
5792901b5c
commit
4338f44955
4 changed files with 404 additions and 338 deletions
Binary file not shown.
|
Before Width: | Height: | Size: 43 KiB After Width: | Height: | Size: 12 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 53 KiB After Width: | Height: | Size: 66 KiB |
|
|
@ -1,9 +1,15 @@
|
|||
[[user-profile]]
|
||||
= Defining a user profile
|
||||
|
||||
In {project_name} a user is associated with a set of attributes. These attributes are used to better describe and identify users within {project_name} as well as to pass over additional information about them to applications.
|
||||
In {project_name} a user is associated with a set of attributes. These attributes are used to better describe and identify
|
||||
users within {project_name} as well as to pass over additional information about them to applications.
|
||||
|
||||
A user profile defines a well-defined schema for representing user attributes and how they are managed within a realm. By providing a consistent view over user information, it allows administrators to control the different aspects on how attributes are managed as well as to make it much easier to extend {project_name} to support additional attributes.
|
||||
A user profile defines a well-defined schema for representing user attributes and how they are managed within a realm.
|
||||
By providing a consistent view over user information, it allows administrators to control the different aspects on how
|
||||
attributes are managed as well as to make it much easier to extend {project_name} to support additional attributes.
|
||||
|
||||
Although the user profile is mainly targeted for attributes that end-users can manage (e.g.: first and last names, phone, etc)
|
||||
it also serves for managing any other metadata you want to associate with your users.
|
||||
|
||||
Among other capabilities, user profile enables administrators to:
|
||||
|
||||
|
|
@ -13,46 +19,100 @@ Among other capabilities, user profile enables administrators to:
|
|||
* Dynamically enforce user profile compliance so that user information is always updated and in compliance with the metadata and rules associated with attributes
|
||||
* Define validation rules on a per-attribute basis by leveraging the built-in validators or writing custom ones
|
||||
* Dynamically render forms that users interact with like registration, update profile, brokering, and personal information in the account console, according to the attribute definitions and without any need to manually change themes.
|
||||
* Customize user management interfaces in the administration console so that attributes are rendered dynamically based on the user profile schema
|
||||
|
||||
The User Profile capabilities are backed by the User Profile SPI. By default, these capabilities are disabled and realms are configured to use a default configuration that keeps backward compatibility with the legacy behavior.
|
||||
The user profile schema or configuration uses a <<_user-profile-json-configuration,JSON>> format to represent attributes and their metadata. From the administration console,
|
||||
you are able to manage the configuration by clicking on the `Realm Settings` on the left side menu and then clicking on the `User Profile` tab on that page.
|
||||
|
||||
In the next sections, we'll be looking at how to create your own user profile schema or configuration, and how to manage attributes.
|
||||
|
||||
== Understanding the Default Configuration
|
||||
|
||||
By default, {project_name} provides a basic user profile configuration covering some of the most common user attributes:
|
||||
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Name
|
||||
|Description
|
||||
| `username` | The username
|
||||
| `email` | End-User's preferred e-mail address.
|
||||
| `firstName` | Given name(s) or first name(s) of the end-user
|
||||
| `lastName` | Surname(s) or last name(s) of the End-User
|
||||
|===
|
||||
|
||||
In {project_name}, both `username` and `email` attributes have a special handling as they are often used to identify, authenticate,
|
||||
and link user accounts. For those attributes, you are limited to changing their settings, and you can not remove them.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The legacy behavior is about keeping the default constraints used by {project_name} when managing users root attributes such as username, email, first and last name, without any restriction on how custom attributes are managed. Regarding user flows such as registration, profile update, brokering, and managing accounts through the account console, users are restricted to use the attributes aforementioned with the possibility to change theme templates to support additional attributes.
|
||||
|
||||
If you are already using {project_name}, the legacy behavior is what you have been using so far.
|
||||
The behavior of both `username` and `email` attributes changes accordingly to the `Login` settings of your realm. For instance,
|
||||
changing the `Email as username` or the `Edit username` settings will override any configuration you have set in the user profile configuration.
|
||||
====
|
||||
|
||||
Differently than the legacy behavior, the declarative provider gives you a lot more flexibility to define the user profile configuration to a realm through the administration console and a well-defined JSON schema.
|
||||
As you will see in the following sections, you are free to change the default configuration by bringing your own attributes
|
||||
or changing the settings for any of the available attributes to better fit it to your needs.
|
||||
|
||||
In the next sections, we'll be looking at how to use the declarative provider to define your own user profile configuration.
|
||||
== Understanding the User Profile Contexts
|
||||
|
||||
In {project_name}, users are managed through different contexts:
|
||||
|
||||
* Registration
|
||||
* Update Profile
|
||||
* Reviewing Profile when authenticating through a broker or social provider
|
||||
* Account Console
|
||||
* Administrative (e.g.: administration console and Admin REST API)
|
||||
|
||||
Except for the `Administrative` context, all other contexts are considered end-user contexts as they are related to user self-service
|
||||
flows.
|
||||
|
||||
Knowing these contexts is important to understand where your user profile configuration will take effect when managing users.
|
||||
Regardless of the context where the user is being managed, the same user profile configuration will be used to render UIs and validate
|
||||
attribute values.
|
||||
|
||||
As you will see in the following sections, you might restrict certain attributes to be available only from the administrative context and disable them
|
||||
completely for end-users. The other way around is also true if you don't want administrators to have access to certain user attributes but only the end-user.
|
||||
|
||||
[[_understanding-managed-and-unmanaged-attributes]]
|
||||
== Understanding Managed and Unmanaged Attributes
|
||||
|
||||
By default, {project_name} will only recognize the attributes defined in your user profile configuration.
|
||||
The server ignores any other attribute not explicitly defined there.
|
||||
|
||||
By being strict about which user attributes can be set to your users, as well as how their values are validated,
|
||||
{project_name} can add another defense barrier to your realm and help you to prevent unexpected attributes and values associated to your users.
|
||||
|
||||
That said, user attributes can be categorized as follows:
|
||||
|
||||
* *Managed*. These are attributes controlled by your user profile, to which you want to allow end-users and administrators
|
||||
to manage from any user profile context.
|
||||
For these attributes, you want complete control on how and when they are managed.
|
||||
* *Unmanaged*. These are attributes you do not explicitly define in your user profile so that they are completely ignored by {project_name}, by default.
|
||||
|
||||
Although unmanaged attributes are disabled by default, you can configure your realm using different policies to define how they are handled by the server.
|
||||
For that, click on the `Realm Settings` at the left side menu, click on the `General` tab, and then choose any of the following options from the `Unmanaged Attributes` setting:
|
||||
|
||||
* *Disabled*. This is the default policy so that unmanaged attributes are disabled from all user profile contexts.
|
||||
* *Enabled*. This policy enables unmanaged attributes to all user profile contexts.
|
||||
* *Admin can view*. This policy enables unmanaged attributes only from the administrative context as read-only.
|
||||
* *Admin can edit*. This policy enables unmanaged attributes only from the administrative context for reads and writes.
|
||||
|
||||
These policies give you a fine-grained control over how the server will handle unmanaged attributes.
|
||||
You can choose to completely disable or only support unmanaged attributes when managing users through the administrative context.
|
||||
|
||||
When unmanaged attributes are enabled (even if partially) you can manage them from the administration console at the `Attributes` tab in the User Details UI.
|
||||
If the policy is set to `Disabled` this tab is not available.
|
||||
|
||||
As a recommendation, try to adhere to the most strict policy as much as possible (e.g.: `Disabled` or `Admin can edit`) to prevent unexpected
|
||||
attributes (and values) set to your users when they are managing their profile through end-user contexts.
|
||||
Avoid setting the `Enabled` policy and prefer defining all the attributes that end-users can manage in your user profile configuration, under your control.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
In the future, the legacy behavior will no longer be supported in {project_name}. Ideally, you should start looking at the new capabilities provided by the User Profile and migrate your realms accordingly.
|
||||
The `Enabled` policy is targeted for realms migrating from previous versions of {project_name} and to avoid breaking
|
||||
behavior when using custom themes and extending the server with their own custom user attributes.
|
||||
====
|
||||
|
||||
== Enabling the User Profile
|
||||
|
||||
:tech_feature_name: Declarative User Profile
|
||||
:tech_feature_setting: -Dkeycloak.profile.feature.declarative_user_profile=enabled
|
||||
:tech_feature_id: declarative-user-profile
|
||||
include::../templates/techpreview.adoc[]
|
||||
|
||||
In addition to enabling the `declarative_user_profile` feature, you should enable User Profile for a realm. To do that, click on the `Realm Settings` link on
|
||||
the left side menu and turn on the `User Profile Enabled` switch.
|
||||
|
||||
image:images/user-profile-enabling.png[]
|
||||
|
||||
Once you enable it and click on the `Save` button, you can access the `User Profile` tab from where you can manage the configuration for user attributes.
|
||||
|
||||
By enabling the user profile for a realm, {project_name} is going to impose additional constraints on how attributes are managed based on the user profile configuration. In summary, here is the list of what you should expect when the feature is enabled:
|
||||
|
||||
* From an administration point of view, the `Attributes` tab at the user details page will only show the attributes defined in the user profile configuration. The conditions defined on a per-attribute basis will also be taken into account when managing attributes.
|
||||
|
||||
* User facing forms like registration, update profile, brokering, and personal info in the account console, are going to be rendered dynamically based on the user profile configuration. For that, {project_name} is going to rely on different templates to render these forms dynamically.
|
||||
|
||||
In the next topics, we'll be exploring how to manage the user profile configuration and how it affects your realm.
|
||||
As you will see in the following sections, you can also restrict the audience for an attribute by choosing if it should be visible or writable by users and/or administrators.
|
||||
|
||||
== Managing the User Profile
|
||||
|
||||
|
|
@ -62,24 +122,20 @@ The user profile configuration is managed on a per-realm basis. For that, click
|
|||
.User Profile Tab
|
||||
image:images/user-profile-tab.png[]
|
||||
|
||||
In the `Attributes` sub-tab you have a list of the attributes currently associated with the user profile. By default, the configuration is created based on the user root attributes and each attribute is configured with some defaults in terms of validation and permissioning.
|
||||
In the `Attributes` sub-tab you have a list of all managed attributes.
|
||||
|
||||
In the `Attribute Groups` sub-tab you can manage attribute groups. An attribute group allows you to correlate attributes so that they are displayed together when rendering user facing forms.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
For now, attribute groups are only used for rendering purposes but in the future they should also enable defining top-level configurations to the attributes they are linked to.
|
||||
====
|
||||
In the `JSON Editor` sub-tab you can view and edit the <<_user-profile-json-configuration,JSON>> configuration. You can use this tab
|
||||
to grab your current configuration or manage it manually. Any change you make to this tab is reflected in the other tabs, and vice-versa.
|
||||
|
||||
In the `JSON Editor` sub-tab you can view and edit the configuration using a well-defined JSON schema. Any change you make when at any other tab are reflected in the JSON configuration shown at this tab.
|
||||
|
||||
In the next section, you are going to learn how to manage the configuration from the `Attributes` sub-tab.
|
||||
In the next section, you are going to learn how to manage attributes.
|
||||
|
||||
== Managing Attributes
|
||||
|
||||
At the `Attributes` sub-tab you can create, edit, and delete the attributes associated with the user profile.
|
||||
At the `Attributes` sub-tab you can create, edit, and delete the managed attributes.
|
||||
|
||||
To define a new attribute and associate it with the user profile, click on the *Create attribute* button at the top the attribute listing.
|
||||
To define a new attribute and associate it with the user profile, click on the *Create attribute* button at the top of the attribute listing.
|
||||
|
||||
.Attribute Configuration
|
||||
image:images/user-profile-create-attribute.png[]
|
||||
|
|
@ -87,74 +143,67 @@ image:images/user-profile-create-attribute.png[]
|
|||
When configuring the attribute you can define the following settings:
|
||||
|
||||
Name::
|
||||
The name of the attribute.
|
||||
The name of the attribute, used to uniquely identify an attribute.
|
||||
|
||||
Display name::
|
||||
A user-friendly name for the attribute, mainly used when rendering user-facing forms. It supports internationalization so that values can be loaded from message bundles.
|
||||
A user-friendly name for the attribute, mainly used when rendering user-facing forms. It also supports link:#_using-internationalized-messages[Using Internationalized Messages]
|
||||
|
||||
Attribute Group::
|
||||
The attribute group to which the attribute belongs to, if any.
|
||||
|
||||
Enabled when scope::
|
||||
Allows you to define a list of scopes to dynamically enable an attribute. If not set, the attribute is always enabled and its constraints are always enforced when managing user profiles as well as when rendering user-facing forms. Otherwise, the same constraints only apply when any of the scopes in the list is requested by clients.
|
||||
|
||||
Enabled when::
|
||||
Enables or disables an attribute. If set to `Always`, the attribute is available from any user profile context.
|
||||
If set to `Scopes are requested`, the attribute is only available when the client acting on behalf of the user is requesting a
|
||||
set of one or more scopes. You can use this option to dynamically enforce certain attributes depending on the client scopes
|
||||
being requested. For the account and administration consoles, scopes are not evaluated and the attribute is always enabled.
|
||||
That is because filtering attributes by scopes only works when running authentication flows.
|
||||
|
||||
Required::
|
||||
Set the attribute as required. If not enabled, the attribute is optional. Otherwise, the attribute must be provided by users and administrators with the possibility to also make the attribute required only for users or administrators as well as based on the scopes requested by clients.
|
||||
Set the conditions to mark an attribute as required. If disabled, the attribute is optional.
|
||||
If enabled, you can set the `Required for` setting to mark the attribute as required depending on the user profile context so that
|
||||
the attribute is required for end-users (via end-user contexts) or to administrators (via administrative context), or both.
|
||||
You can also set the `Required when` setting to mark the attribute as required only when a set of one or more client scopes are requested.
|
||||
If set to `Always`, the attribute is required from any user profile context.
|
||||
If set to `Scopes are requested`, the attribute is only required when the client acting on behalf of the user is requesting a
|
||||
set of one or more scopes. For the account and administration consoles, scopes are not evaluated and the attribute is not required.
|
||||
That is because filtering attributes by scopes only works when running authentication flows.
|
||||
|
||||
Permission::
|
||||
In this section, you can define read and write permissions for users and administrators.
|
||||
In this section, you can define read and write permissions when the attribute is being managed from an end-user or administrative context.
|
||||
The `Who can edit` setting mark an attribute as writable by `User` and/or `Admin`, from an end-user and administrative context, respectively.
|
||||
The `Who can view` setting mark an attribute as read-only by `User` and/or `Admin` from an end-user and administrative context, respectively.
|
||||
|
||||
Validation::
|
||||
In this section, you can define the validations that will be performed when managing the attribute value. {project_name} provides a set of built-in validators you can choose from with the possibility to add your own.
|
||||
In this section, you can define the validations that will be performed when managing the attribute value.
|
||||
{project_name} provides a set of built-in validators you can choose from with the possibility to add your own. For more details, look at
|
||||
the link:#_validating-attributes[Validating Attributes] section.
|
||||
|
||||
Annotation::
|
||||
In this section, you can associate annotations to the attribute. Annotations are mainly useful to pass over additional metadata to frontends for rendering purposes.
|
||||
For more details, look at the link:#_defining-ui-annotations[Defining UI Annotations] section.
|
||||
|
||||
=== Managing Permissions
|
||||
When you create an attribute, the attribute is only available from administrative contexts to avoid unexpectedly exposing attributes to end-users.
|
||||
Effectively, the attribute won't be accessible to end-users when they are managing their profile through the end-user contexts. You can change the `Permissions` settings anytime accordingly
|
||||
to your needs.
|
||||
|
||||
In the `Permission` section, you can define the level of access users and administrators have to read and write to an attribute.
|
||||
[[_validating-attributes]]
|
||||
== Validating Attributes
|
||||
|
||||
.Attribute Permission
|
||||
image:images/user-profile-permission.png[]
|
||||
|
||||
For that, you can use the following settings:
|
||||
|
||||
Can user view?::
|
||||
If enabled, users can view the attribute. Otherwise, users don't have access to the attribute.
|
||||
|
||||
Can user edit?::
|
||||
If enabled, users can view and edit the attribute. Otherwise, users don't have access to write to the attribute.
|
||||
|
||||
Can admin view?::
|
||||
If enabled, administrators can view the attribute. Otherwise, administrators don't have access to the attribute.
|
||||
|
||||
Can admin edit?::
|
||||
If enabled, administrators can view and edit the attribute. Otherwise, administrators don't have access to write to the attribute.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
When you create an attribute, no permission is set to the attribute. Effectively, the attribute won't be accessible by either users or administrators. Once you create the attribute, make sure to set the permissions accordingly to that the attribute is only visible by the target audience.
|
||||
====
|
||||
|
||||
Permissioning has a direct impact on how and who can manage the attribute, as well as on how the attribute is rendered in user-facing forms.
|
||||
|
||||
For instance, by marking an attribute as only viewable by users, the administrators won't have access to the attribute when managing users through the administration console (neither from the User API). Also, users won't be able to change the attribute when updating their profiles. An interesting configuration if user attributes are fetched from an existing identity store (federation) and you just want to make attributes visible to users without any possibility to update the attribute other than through the source identity store.
|
||||
|
||||
Similarly, you can also mark an attribute as writable only for administrators with read-only access for users. In this case, only administrators are going to be allowed to manage the attribute.
|
||||
|
||||
Depending on your privacy requirements, you might also want attributes inaccessible to administrators but with read-write permissions for users.
|
||||
|
||||
Make sure to set the correct permissions whenever you add a new attribute to the user profile configuration.
|
||||
|
||||
=== Managing validations
|
||||
|
||||
In the `Validation` section, you can choose from different forms of validation to make sure the attribute value conforms to specific rules.
|
||||
You can enable validation to managed attributes to make sure the attribute value conforms to specific rules.
|
||||
For that, you can add or remove validators from the `Validations` settings when managing an attribute.
|
||||
|
||||
.Attribute Validation
|
||||
image:images/user-profile-validation.png[]
|
||||
|
||||
{project_name} provides different validators out of the box:
|
||||
Validation happens at any time when writing to an attribute, and they can throw errors that will be shown in UIs when the value
|
||||
fails a validation.
|
||||
|
||||
=== Built-in Validators
|
||||
|
||||
{project_name} provides some built-in validators that you can choose from, and you are also able to provide
|
||||
your own validators by extending the `Validator SPI`.
|
||||
|
||||
The list below provides a list of all the built-in validators:
|
||||
|
||||
[cols="3*", options="header"]
|
||||
|===
|
||||
|
|
@ -227,252 +276,40 @@ image:images/user-profile-validation.png[]
|
|||
|
||||
*options*: array of strings containing allowed values.
|
||||
|
||||
|up-username-not-idn-homograph
|
||||
|The field can contain only latin characters and common unicode characters. Useful for the fields, which can be subject of IDN homograph attacks (typically username).
|
||||
|
|
||||
|
||||
*error-message*: the key of the error message in i18n bundle. If not set a generic message is used.
|
||||
|
||||
|===
|
||||
|
||||
==== Managing annotations
|
||||
[[_defining-ui-annotations]]
|
||||
== Defining UI Annotations
|
||||
|
||||
In order to pass additional information to frontends, attributes can be decorated with
|
||||
annotations to dictate how attributes are rendered. This capability is mainly useful when extending {project_name} themes
|
||||
to render pages dynamically based on the annotations associated with attributes.
|
||||
This mechanism is used for example to link:#_configuring_form_input_field_for_attribute[configure Form input filed for attribute].
|
||||
|
||||
Annotations are used, for example, for link:#_changing-the-html-type-for-an-attribute[Changing the HTML `type` for an Attribute] and link:#_changing-the-dom-representation-of-an-attribute[Changing the DOM representation of an Attribute], as you will
|
||||
see in the following sections.
|
||||
|
||||
.Attribute Annotation
|
||||
image:images/user-profile-annotation.png[]
|
||||
|
||||
== Managing Attribute Groups
|
||||
|
||||
At the `Attribute Groups` sub-tab you can create, edit, and delete attribute groups. An attribute group allows you to define a container for correlated attributes so that they are rendered together when at the user-facing forms.
|
||||
|
||||
.Attribute Group List
|
||||
image:images/user-profile-attribute-group-list.png[]
|
||||
An annotation is a key/value pair shared with the UI so that they can change how the HTML element corresponding to the attribute is rendered.
|
||||
You can set any annotation you want to an attribute as long as the annotation is supported by the theme your realm is using.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You can't delete attribute groups that are bound to attributes. For that, you should first update the attributes to remove the binding.
|
||||
The only restriction you have is to avoid using annotations using the `kc` prefix in their keys because these annotations
|
||||
using this prefix are reserved for {project_name}.
|
||||
====
|
||||
|
||||
To create a new group, click on the *Create attributes group* button on the top of the attribute groups listing.
|
||||
=== Built-in Annotations
|
||||
|
||||
.Attribute Group Configuration
|
||||
image:images/user-profile-create-attribute-group.png[]
|
||||
The following annotations are supported by {project_name} built-in themes:
|
||||
|
||||
When configuring the group you can define the following settings:
|
||||
|
||||
Name::
|
||||
The name of the group.
|
||||
|
||||
Display name::
|
||||
A user-friendly name for the group, mainly used when rendering user-facing forms. It supports internationalization so that values can be loaded from message bundles.
|
||||
|
||||
Display description::
|
||||
A user-friendly text that will be displayed as a tooltip when rendering user-facing forms.
|
||||
|
||||
Annotation::
|
||||
In this section, you can associate annotations to the attribute. Annotations are mainly useful to pass over additional metadata to frontends for rendering purposes.
|
||||
|
||||
== Using the JSON configuration
|
||||
|
||||
The user profile configuration is stored using a well-defined JSON schema. You can choose from editing the user profile configuration directly by clicking on the `JSON Editor` sub-tab.
|
||||
|
||||
.JSON Configuration
|
||||
image:images/user-profile-json-config.png[]
|
||||
|
||||
The JSON schema is defined as follows:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {
|
||||
"roles": [ "user", "admin" ],
|
||||
"scopes": [ "foo", "bar" ]
|
||||
},
|
||||
"permissions": {
|
||||
"view": [ "admin", "user" ],
|
||||
"edit": [ "admin", "user" ]
|
||||
},
|
||||
"validations": {
|
||||
"email": {
|
||||
"max-local-length": 64
|
||||
},
|
||||
"length": {
|
||||
"max": 255
|
||||
}
|
||||
},
|
||||
"annotations": {
|
||||
"myannotation": "myannotation-value"
|
||||
}
|
||||
}
|
||||
],
|
||||
"groups": [
|
||||
{
|
||||
"name": "personalInfo",
|
||||
"displayHeader": "Personal Information"
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
The schema supports as many attributes as you need.
|
||||
|
||||
For each attribute you should define a `name` and, optionally, the `required`, `permission`, and the `annotations` settings.
|
||||
|
||||
=== Required property
|
||||
|
||||
The `required` setting defines whether an attribute is required. {project_name} allows you to set an attribute as required based on different conditions.
|
||||
|
||||
When the `required` setting is defined as an empty object, the attribute is always required.
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
On the other hand, you can choose to make the attribute required only for users, or administrators, or both. As well as mark the attribute as required only in case a specific scope is requested when the user is authenticating in {project_name}.
|
||||
|
||||
To mark an attribute as required for a user and/or administrator, set the `roles` property as follows:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {
|
||||
"roles": ["user"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
The `roles` property expects an array whose values can be either `user` or `admin`, depending on whether the attribute is required by the user or the administrator, respectively.
|
||||
|
||||
Similarly, you can choose to make the attribute required when a set of one or more scopes is requested by a client when authenticating a user. For that, you can use the `scopes` property as follows:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {
|
||||
"scopes": ["foo"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
The `scopes` property is an array whose values can be any string representing a client scope.
|
||||
|
||||
=== Permissions property
|
||||
|
||||
The attribute-level `permissions` property can be used to define the read and write permissions to an attribute. The permissions are set based on whether these operations can be performed on the attribute by a user, or administrator, or both.
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"permissions": {
|
||||
"view": ["admin"],
|
||||
"edit": ["user"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
Both `view` and `edit` properties expect an array whose values can be either `user` or `admin`, depending on whether the attribute is viewable or editable by the user or the administrator, respectively.
|
||||
|
||||
When the `edit` permission is granted, the `view` permission is implicitly granted.
|
||||
|
||||
=== Annotations property
|
||||
|
||||
The attribute-level `annotation` property can be used to associate additional metadata to attributes. Annotations are mainly useful for passing over additional information about attributes to frontends rendering user attributes based on the user profile configuration. Each annotation is a key/value pair.
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"annotations": {
|
||||
"foo": ["foo-value"],
|
||||
"bar": ["bar-value"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
== Using dynamic forms
|
||||
|
||||
One of the main capabilities of User Profile is the possibility to dynamically render user-facing forms based on attributes metadata. When you have the feature enabled to your realm, forms like registration and update profile are rendered using specific theme templates to dynamically render pages based on the user profile configuration.
|
||||
|
||||
That said, you shouldn't need to customize templates at all if the default rendering mechanisms serves to your needs. In case you still need customizations to themes, here are the templates you should be looking at:
|
||||
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Template
|
||||
|Description
|
||||
|
||||
| base/login/update-user-profile.ftl
|
||||
| The template that renders the update profile page.
|
||||
|
||||
| base/login/register-user-profile.ftl
|
||||
| The template that renders the registration page.
|
||||
|
||||
| base/login/idp-review-user-profile.ftl
|
||||
| The template that renders the page to review/update the user profile when federating users through brokering.
|
||||
|
||||
| base/login/user-profile-commons.ftl
|
||||
| The template that renders input fields in forms based on attributes configuration. Used from all three page templates described above. New input types can be implemented here.
|
||||
|
||||
|===
|
||||
|
||||
The default rendering mechanism provides the following capabilities:
|
||||
|
||||
* Dynamically display fields based on the permissions set to attributes.
|
||||
* Dynamically render markers for required fields based on the constraints set to the attributes.
|
||||
* Dynamically render field input type (text, date, number, select, multiselect) set to an attribute.
|
||||
* Dynamically render read-only fields depending on the permissions set to an attribute.
|
||||
* Dynamically order fields depending on the order set to the attributes.
|
||||
* Dynamically group fields that belong to a same attribute group.
|
||||
|
||||
=== Ordering attributes
|
||||
|
||||
The attributes order is set by dragging and dropping the attribute rows on the attribute listing page.
|
||||
|
||||
.Ordering Attributes
|
||||
image:images/user-profile-attribute-list-order.png[]
|
||||
|
||||
The order you set in this page is respected when fields are rendered in dynamic forms.
|
||||
|
||||
=== Grouping attributes
|
||||
|
||||
When dynamic forms are rendered, they will try to group together attributes that belong to a same attribute group.
|
||||
|
||||
.Dynamic Update Profile Form
|
||||
image:images/user-profile-update-profile.png[]
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
When attributes are linked to an attribute group, the attribute order is also important to make sure attributes within the same group are close together, within a same group header. Otherwise, if attributes within a group do not have a sequential order you might have the same group header rendered multiple times in the dynamic form.
|
||||
====
|
||||
|
||||
[[_configuring_form_input_field_for_attribute]]
|
||||
=== Configuring Form input filed for Attributes
|
||||
|
||||
{project_name} provides built-in annotations to configure which input type will be used for the attribute in dynamic forms and other aspects of it's visualization.
|
||||
|
||||
Available annotations are:
|
||||
[cols="2*", options="header"]
|
||||
|===
|
||||
|Name
|
||||
|
|
@ -555,7 +392,11 @@ Field types use HTML form field tags and attributes applied to them - they behav
|
|||
Visual rendering also depends on css styles applied in the used theme.
|
||||
====
|
||||
|
||||
Available `inputType` annotation values:
|
||||
[[_changing-the-html-type-for-an-attribute]]
|
||||
=== Changing the HTML `type` for an Attribute
|
||||
|
||||
You can change the `type` of a HTML5 input element by setting the `inputType` annotation. The available types are:
|
||||
|
||||
[cols="3*", options="header"]
|
||||
|===
|
||||
|Name
|
||||
|
|
@ -629,7 +470,7 @@ Available `inputType` annotation values:
|
|||
|===
|
||||
|
||||
[[_managing_options_for_select_fields]]
|
||||
==== Defining options for select and multiselect fields
|
||||
=== Defining options for select and multiselect fields
|
||||
|
||||
Options for select and multiselect fields are taken from validation applied to the attribute to be
|
||||
sure validation and field options presented in UI are always consistent. By default, options are taken from built-in `options` validation.
|
||||
|
|
@ -649,7 +490,7 @@ image:images/user-profile-select-options-simple-i18n.png[]
|
|||
Localized UI label texts for option value have to be provided by `userprofile.jobtitle.sweng` and `userprofile.jobtitle.swarch`
|
||||
keys then, using common localization mechanism.
|
||||
|
||||
You can also use `inputOptionLabels` annotation to provide labels for individual options. It contains map of labels for option - key in the map is
|
||||
You can also use `inputOptionLabels` annotation to provide labels for individual options. It contains a map of labels for option - key in the map is
|
||||
option value (defined in validation), and value in the map is UI label text itself or its internationalization pattern (like `${i18n.key}`) for that option.
|
||||
|
||||
[NOTE]
|
||||
|
|
@ -720,19 +561,246 @@ provided by built-in `options` validation.
|
|||
.Options provided by custom validator
|
||||
image:images/user-profile-select-options-custom-validator.png[]
|
||||
|
||||
[[_adding-custom-html5-data-attributes]]
|
||||
==== Adding Custom HTML5 Data Attributes
|
||||
[[_changing-the-dom-representation-of-an-attribute]]
|
||||
=== Changing the DOM representation of an Attribute
|
||||
|
||||
You can enable additional client-side behavior by using `kc*` annotations. These annotations are going to be added
|
||||
automatically to a field as a HTML5 attribute prefixed with `data-` and a script with the same will be loaded to the dynamic pages.
|
||||
You can enable additional client-side behavior by setting annotations with the `kc` prefix. These annotations are going to
|
||||
translate into an HTML attribute in the corresponding element of an attribute, prefixed with `data-`, and a script with
|
||||
the same name will be loaded to the dynamic pages so that you can select elements from the DOM based on the custom `data-` attribute
|
||||
and decorate them accordingly by modifying their DOM representation.
|
||||
|
||||
For instance, if you add a `kcMyCustomValidation` annotation to a field, the dynamic pages will add a `data-kcMyCustomValidation` HTML5 attribute
|
||||
to the field and load a JS script file from `<THEME TYPE>/resources/js/kcMyCustomValidation.js`. See the {developerguide_link}[{developerguide_name}] for more information about
|
||||
For instance, if you add a `kcMyCustomValidation` annotation to a field, the HTML attribute `data-kcMyCustomValidation` is added to
|
||||
the corresponding HTML element for the attribute, and a JavaScript file is loaded from your custom theme at `<THEME TYPE>/resources/js/kcMyCustomValidation.js`. See the {developerguide_link}[{developerguide_name}] for more information about
|
||||
how to deploy a custom JS script file to your theme.
|
||||
|
||||
== Forcing User Profile compliance
|
||||
== Managing Attribute Groups
|
||||
|
||||
In order to make sure user profiles are in compliance with the configuration, administrators may use the `VerifyProfile` required action to eventually force users to update their profiles when authenticating to {project_name}.
|
||||
At the `Attribute Groups` sub-tab you can create, edit, and delete attribute groups. An attribute group allows you to define a container for correlated attributes so that they are rendered together when at the user-facing forms.
|
||||
|
||||
.Attribute Group List
|
||||
image:images/user-profile-attribute-group-list.png[]
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You can't delete attribute groups that are bound to attributes. For that, you should first update the attributes to remove the binding.
|
||||
====
|
||||
|
||||
To create a new group, click on the *Create attributes group* button on the top of the attribute groups listing.
|
||||
|
||||
.Attribute Group Configuration
|
||||
image:images/user-profile-create-attribute-group.png[]
|
||||
|
||||
When configuring the group you can define the following settings:
|
||||
|
||||
Name::
|
||||
The name of the attribute, used to uniquely identify an attribute.
|
||||
|
||||
Display name::
|
||||
A user-friendly name for the attribute, mainly used when rendering user-facing forms. It also supports link:#_using-internationalized-messages[Using Internationalized Messages]
|
||||
|
||||
Display description::
|
||||
A user-friendly text that will be displayed as a tooltip when rendering user-facing forms. It also supports link:#_using-internationalized-messages[Using Internationalized Messages]
|
||||
|
||||
Annotation::
|
||||
In this section, you can associate annotations to the attribute. Annotations are mainly useful to pass over additional metadata to frontends for rendering purposes.
|
||||
|
||||
[[_user-profile-json-configuration]]
|
||||
== Using the JSON configuration
|
||||
|
||||
The user profile configuration is stored using a well-defined JSON schema. You can choose from editing the user profile configuration directly by clicking on the `JSON Editor` sub-tab.
|
||||
|
||||
.JSON Configuration
|
||||
image:images/user-profile-json-config.png[]
|
||||
|
||||
The JSON schema is defined as follows:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"unmanagedAttributePolicy": "DISABLED",
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {
|
||||
"roles": [ "user", "admin" ],
|
||||
"scopes": [ "foo", "bar" ]
|
||||
},
|
||||
"permissions": {
|
||||
"view": [ "admin", "user" ],
|
||||
"edit": [ "admin", "user" ]
|
||||
},
|
||||
"validations": {
|
||||
"email": {
|
||||
"max-local-length": 64
|
||||
},
|
||||
"length": {
|
||||
"max": 255
|
||||
}
|
||||
},
|
||||
"annotations": {
|
||||
"myannotation": "myannotation-value"
|
||||
}
|
||||
}
|
||||
],
|
||||
"groups": [
|
||||
{
|
||||
"name": "personalInfo",
|
||||
"displayHeader": "Personal Information",
|
||||
"annotations": {
|
||||
"foo": ["foo-value"],
|
||||
"bar": ["bar-value"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
The schema supports as many attributes and groups as you need.
|
||||
|
||||
The `unmanagedAttributePolicy` property defines the unmanaged attribute policy by setting one of following values. For more details,
|
||||
look at the link:#_understanding-managed-and-unmanaged-attributes[Understanding Managed and Unmanaged Attributes].
|
||||
|
||||
* `DISABLED`
|
||||
* `ENABLED`
|
||||
* `ADMIN_VIEW`
|
||||
* `ADMIN_EDIT`
|
||||
|
||||
=== Attribute Schema
|
||||
|
||||
For each attribute you should define a `name` and, optionally, the `required`, `permission`, and the `annotations` settings.
|
||||
|
||||
The `required` property defines whether an attribute is required. {project_name} allows you to set an attribute as required based on different conditions.
|
||||
|
||||
When the `required` property is defined as an empty object, the attribute is always required.
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
On the other hand, you can choose to make the attribute required only for users, or administrators, or both. As well as mark the attribute as required only in case a specific scope is requested when the user is authenticating in {project_name}.
|
||||
|
||||
To mark an attribute as required for a user and/or administrator, set the `roles` property as follows:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {
|
||||
"roles": ["user"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
The `roles` property expects an array whose values can be either `user` or `admin`, depending on whether the attribute is required by the user or the administrator, respectively.
|
||||
|
||||
Similarly, you can choose to make the attribute required when a set of one or more scopes is requested by a client when authenticating a user. For that, you can use the `scopes` property as follows:
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"required": {
|
||||
"scopes": ["foo"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
The `scopes` property is an array whose values can be any string representing a client scope.
|
||||
|
||||
The attribute-level `permissions` property can be used to define the read and write permissions to an attribute. The permissions are set based on whether these operations can be performed on the attribute by a user, or administrator, or both.
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"permissions": {
|
||||
"view": ["admin"],
|
||||
"edit": ["user"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
Both `view` and `edit` properties expect an array whose values can be either `user` or `admin`, depending on whether the attribute is viewable or editable by the user or the administrator, respectively.
|
||||
|
||||
When the `edit` permission is granted, the `view` permission is implicitly granted.
|
||||
|
||||
The attribute-level `annotation` property can be used to associate additional metadata to attributes. Annotations are mainly useful for passing over additional information about attributes to frontends rendering user attributes based on the user profile configuration. Each annotation is a key/value pair.
|
||||
|
||||
[source,json]
|
||||
----
|
||||
{
|
||||
"attributes": [
|
||||
{
|
||||
"name": "myattribute",
|
||||
"annotations": {
|
||||
"foo": ["foo-value"],
|
||||
"bar": ["bar-value"]
|
||||
}
|
||||
]
|
||||
}
|
||||
----
|
||||
|
||||
=== Attribute Group Schema
|
||||
|
||||
For each attribute group you should define a `name` and, optionally, the `annotations` settings.
|
||||
|
||||
The attribute-level `annotation` property can be used to associate additional metadata to attributes. Annotations are mainly useful for passing over additional information about attributes to frontends rendering user attributes based on the user profile configuration. Each annotation is a key/value pair.
|
||||
|
||||
== Customizing How UIs are Rendered
|
||||
|
||||
The UIs from all the user profile contexts (including the administration console) are rendered dynamically accordingly to your
|
||||
user profile configuration.
|
||||
|
||||
The default rendering mechanism provides the following capabilities:
|
||||
|
||||
* Show or hide fields based on the permissions set to attributes.
|
||||
* Render markers for required fields based on the constraints set to the attributes.
|
||||
* Change the field input type (text, date, number, select, multiselect) set to an attribute.
|
||||
* Mark fields as read-only depending on the permissions set to an attribute.
|
||||
* Order fields depending on the order set to the attributes.
|
||||
* Group fields that belong to the same attribute group.
|
||||
* Dynamically group fields that belong to the same attribute group.
|
||||
|
||||
=== Ordering attributes
|
||||
|
||||
The attribute order is set by dragging and dropping the attribute rows on the attribute listing page.
|
||||
|
||||
.Ordering Attributes
|
||||
image:images/user-profile-attribute-list-order.png[]
|
||||
|
||||
The order you set in this page is respected when fields are rendered in dynamic forms.
|
||||
|
||||
=== Grouping attributes
|
||||
|
||||
When dynamic forms are rendered, they will try to group together attributes that belong to the same attribute group.
|
||||
|
||||
.Dynamic Update Profile Form
|
||||
image:images/user-profile-update-profile.png[]
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
When attributes are linked to an attribute group, the attribute order is also important to make sure attributes within the same group are close together, within a same group header. Otherwise, if attributes within a group do not have a sequential order you might have the same group header rendered multiple times in the dynamic form.
|
||||
====
|
||||
|
||||
== Enabling Progressive Profiling
|
||||
|
||||
In order to make sure end-user profiles are in compliance with the configuration, administrators can use the `VerifyProfile` required action to eventually force users to update their profiles when authenticating to {project_name}.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
|
|
@ -741,24 +809,22 @@ The `VerifyProfile` action is similar to the `UpdateProfile` action. However, it
|
|||
|
||||
When enabled, the `VerifyProfile` action is going to perform the following steps when the user is authenticating:
|
||||
|
||||
* Check whether the user profile is fully compliant with the user profile configuration set to the realm.
|
||||
* Check whether the user profile is fully compliant with the user profile configuration set to the realm. That means running
|
||||
validations and make sure all of them are successful.
|
||||
* If not, perform an additional step during the authentication so that the user can update any missing or invalid attribute.
|
||||
* If the user profile is compliant with the configuration, no additional step is performed, and the user continues with the authentication process.
|
||||
|
||||
By default, the `VerifyProfile` action is disabled. To enabled it, click on the
|
||||
`Authentication` link on the left side menu and then click on the `Required Actions` tab. At this tab, select the *Enabled* switch of the `VerifyProfile` action.
|
||||
The `VerifyProfile` action is enabled by default. To disable it, click on the
|
||||
`Authentication` link on the left side menu and then click on the `Required Actions` tab. At this tab, use the *Enabled* switch of the `VerifyProfile` action to disable it.
|
||||
|
||||
.Registering the VerifyProfile Required Action
|
||||
image:images/user-profile-register-verify-profile-action.png[]
|
||||
|
||||
== Migrating to User Profile
|
||||
[[_using-internationalized-messages]]
|
||||
== Using Internationalized Messages
|
||||
|
||||
Before enabling the User Profile capabilities to a realm, there are some important considerations you should be aware of. By providing a single place to manage attribute metadata, the feature is very strict about the attributes that can be set to users and how they are managed.
|
||||
If you want to use internationalized messages when configuring attributes, attributes groups, and annotations, you can
|
||||
set their display name, description, and values, using a placeholder that will translate to a message from a message bundle.
|
||||
|
||||
In terms of user management, administrators are able to manage only the attributes defined in the user profile configuration. Any other attribute set to the user and not yet defined in the user profile configuration won't be accessible. It is recommended to update your user profile configuration with all the user attributes you want to expose either to users or administrators.
|
||||
|
||||
The same recommendation applies for those accessing the User REST API to query user information.
|
||||
|
||||
In regards to {project_name} internal user attributes such as `LDAP_ID`, `LDAP_ENTRY_DN`, or `KERBEROS_PRINCIPAL`, if you want to be able to access those attributes you should have them as attributes in your user profile configuration. The recommendation is to mark these attributes as viewable only to administrators so that you can look at them when managing the user attributes through the administration console or querying users via User API.
|
||||
|
||||
In regards to theming, if you already have customizations to the legacy templates (those hardcoded with user root attributes) your custom templates won't be used when rendering user-facing forms but the new templates that render these forms dynamically. Ideally, you should avoid having any customizations to templates and try to stick with the behavior provided by these new templates to dynamically render forms for you. If they are still not enough to address your requirements, you can either customize them or provide us with any feedback so that we discuss whether it makes sense to enhance the new templates.
|
||||
For that, you can use a placeholder to resolve messages keys such as `${myAttributeName}`, where `myAttributeName` is the key for a message in a message bundle. For more details,
|
||||
look at link:{developerguide_link}#messages[{developerguide_name}] about how to add message bundles to custom themes.
|
||||
Loading…
Reference in a new issue