You are viewing the documentation for the current version.
This page is also available in versions: 7.6, 7.7, 7.8, 8.0, 8.1, 9.0, 9.1, 9.2, 9.3, 9.4, 9.5 (current), devel

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

9.5:documentation:modules_reg [2018/12/19 07:46] (current)
Line 1: Line 1:
 +<- .:modules | Modules ^ .:start | Documentation ^ .:​modules_openam | Modules: OpenAM authentication ->
  
 +====== Modules - User registration [reg] ======
 +
 +Reg module serves as a registration point for new users to access CzechIdM. To be a registered user, one has to go through several validation steps before he can log in to CzechIdM. Validation steps are configurable in CzechIdM. Enabled module adds new GUI form available via CzechIdM login page and manages all the registration process:
 +
 +{{ :​devel:​documentation:​registration_activity.png?​1200 | Registration process}}
 +
 +====== Obtaining set of registration attributes ======
 +When user tries to access registration form, registration module needs to determine which attributes (or form fields) should be displayed in said form for user to fill out. These attributes are determined by reg form definition and attributes defined in it. The mechanism is same as standard EAV forms.
 +
 +===== Identifier attributes =====
 +Registration module allows to specify set of attributes, which will be used for identity search, when looking up the identity (in ACTIVATION mode), or determining,​ whether the identity exists or not (in REGISTRATION mode). These attributes should be configured in idm.pub.reg.attributes.identifier as a comma separated list of attribute codes. Attributes, defined as identifiers,​ must meet these requirements
 +
 +  * Attribute with the same code must be defined in reg form definition
 +  * Attribute must be either identity attribute, or EAV attribute in default form definition for IdMIdentity
 +  * If EAV attribute is used, then it must be of SHORTTEXT type, otherwise search will not work as intended.
 +
 +==== Example ====
 +
 +  * Attributes in default IdMIdentity form definition : birthNumber,​ address
 +  * Attributes in reg IdMIdentity form definition: username, email, firstName, lastName, birthNumber
 +  * idm.pub.reg.attributes.identifier=username,​email,​birthNumber
 +
 +These settings will display attributes username, email, firstName, lastName, birthNumber in registration form. Attributes username,​email and birthNumber will then be used to determine, whether the identity with these attributes exists in IdM, or not. Attributes username and email will be compared with corresponding identity attributes and attribute birthNumber is compared with the values of the attribute with the same code in default IdmIdentity form definition.
 +
 +===== Validation of registration form =====
 +Validation of registration attributes has two steps: basic fields validation and password validation. In the first phase, module checks, if all required attributes are filled. (Attribute is required if it has required field checked in its configuration in reg form definition, or if its defined as identifier attribute). After that, password is checked against default validation policy.
 +
 +===== Generating login =====
 +Registration module supports various login generators. Name of the login generator can be configured in property idm.pub.reg.loginGenerator. This property should contain full className of login generator, which we want to use. This class must implement eu.bcvsolutions.idm.reg.login.LoginGenerator interface.
 +
 +<​note>​Note that all attributes which are used during registration process must be defined in reg form definition (including username attribute). To prevent username attribute showing in registration form, you can mark it as read-only. Attributes marked as read-only will not be displayed in registration form for user to fill in, but can be filled by defferent menas such as various generators.</​note>​
 +
 +==== BasicLoginGenerator ====
 +
 +Basic login generator is the only login generator shipped with registration module. It uses last name + first character or first name. If that is taken, appends a number.
 +
 +==== Example ====
 +
 +Following configuration shows how to configure BasicLoginGenerator (which is shipped with registration module) as a login generator.
 +
 +  * idm.pub.reg.loginGenerator=eu.bcvsolutions.idm.reg.login.BasicLoginGenerator
 +
 +===== Registration modes =====
 +
 +Registration module supports three registration modes - REGISTRATION,​ ACTIVATION and HYBRID. Main difference between these modes is how they handle identity creation. This is visualized in the activity diagram above.
 +
 +==== Setting registration mode ====
 +
 +Registration mode is set using idm.sec.reg.activationMode. This property can contain one of the following three values : REGISTRATION,​ ACTIVATION, HYBRID.
 +
 +===== Setting attributes and creating identity =====
 +In order to understand how registration module works, we need to explain how and when are fields from registration form set to identity. Right after the validation of registration form, all fields are set to reg EAV form. At this point, you can see all attributes that given user filled in registration form. After registration approval, all attributes are copied from reg form to identity attributes, or default form definition for IdMIdentity.
 +
 +===== Registration confirmation =====
 +
 +By default, a confirmation is required for every user who registers. Registration approval process is displayed on the image bellow
 +
 +{{ :​devel:​documentation:​regapproveuser.png?​600 |}}
 +
 +After approving, the registration process continues with finalization of identity (setting up state and adding roles). In case of denial of registration,​ created identity is deleted and process ends. You can turn off registration approval by disabling RegApproveProcessor.
 +
 +====== Handling password ======
 +
 +There are many ways user can set their password when registering in CzechIdM. The most preferable way is to let user to set their password when filling out registration form. In order to do this, we must set up password attribute in reg EAV definition. In order to do so, we need to do the following:
 +
 +  * Create eav attribute in reg form definition, which has the same code, that is set in idm.pub.reg.attributes.password.attr property
 +  * Set its type to SHORTTEXT
 +  * Mark the attribute as confidential
 +  * Set attributes renderer to Password field
 +
 +Now, new users will be prompted to enter password when filling up registration form. This newly set password is validated against default validation policy. To change that behavior, you can set different policy in idm.sec.reg.passwordPolicy property.
 +
 +<note important>​Password is set to identity at the moment of creation. This means, that only thing, which prevents user to log in before confirmation and approval of registration is fact, that the corresponding identity has not yet been enabled. Also mind that this means, that any accounts, which will be created after registration,​ will have different passwords set to them (if said accounts require password).</​note>​
 +
 +===== Other ways to set user password after registration =====
 +
 +  * Use pasword reset module
 +  * Administrator manually sets users password after registration
 +  * There is an endpoint, which supports setting user password when clicking on confirmation link. This however is not supported in FE, so clients would have to support their own FE page, which si handling this kind of logic.
 +
 +====== "​Accept terms and conditions"​ feature ======
 +
 +Registration module supports feature, which requires users who register to check that they accept terms and conditions. In order to set this up, you need to do the following:
 +
 +  * Create eav attribute in reg form definition
 +  * Set attributes type to Boolean
 +  * Set attributes renderer to "​Terms"​
 +
 +New checkbox will now appear in registration form and users wont be able to submit registration form, unless they check this new checkbox.
 +
 +
 +====== Configuration ======
 +
 +^ Property ​                                   ^ Possible values ​                                                                                       ^ Description ​                                                                                                                                                                                                                                           ^
 +| idm.sec.reg.defaultRoles ​                   | Comma separated list of role codes                                                                     | Setting up this property enables adding roles after registration confirmation. If this property is not set, no roles will be added when user registration is approved ​                                                                                 |
 +| idm.sec.reg.passwordPolicy ​                 | Name of one of the validation password policies ​                                                       | Setting this property changes password policy, which will be used when validating password. If this property is not set, default validation policy is used instead. If property is set and no policy for that name is found, then exception is thrown ​ |
 +| idm.sec.reg.identityStateAfterConfirmation ​ | CREATED, NO\_CONTRACT,​ FUTURE\_CONTRACT,​ VALID, PASSWORD\_EXPIRED,​ LEFT, DISABLED, DISABLED\_MANUALLY ​ | This property contains value of state, which will be set to identity after registration approval. Note that this could get overwritten by HR processes. ​                                                                                               |
 +| idm.reg.sec.confirmationTtlSec ​             | Positive integer number ​                                                                               | Sets duration for how long is confirmation token valid (in seconds) ​                                                                                                                                                                                   |
 +| idm.pub.reg.loginGenerator ​                 | Full class name                                                                                        | Contains class name of login generator, which should be used for generating of login. If this property is not set, then generating of logins will not be enabled and not entering username in registration form will result in error. ​                 |
 +| idm.sec.reg.defaultOrgId ​                   | UUID                                                                                                   | Contains identifier of treeNode, which will be set as work position for registered users contract. ​                                                                                                                                                    |
 +| idm.sec.reg.defaultAuthorizer ​              | Username ​                                                                                              | Username for user, which should be used as a default guarantee for registered users contract. ​                                                                                                                                                         |
 +| idm.pub.reg.passwordInputEnabled ​           | true/​false ​                                                                                            | Turns password validation on and off                                                                                                                                                                                                                   |
 +| idm.pub.reg.attributes.password.attr ​       | String ​                                                                                                | Name of reg eav attribute used to store password. This must be set, otherwise users would not be able to log in.                                                                                                                                       |
 +| idm.sec.reg.defaultAttributeType ​           | CHAR, SHORTTEXT, TEXT, INT, LONG, DOUBLE, BOOLEAN, DATE, DATETIME, BYTEARRAY, UUID                     | Type of EAV used to build query to search identities. Only SHORTTEXT is supported now.                                                                                                                                                                 |
 +| idm.pub.reg.attributes.identifier ​          | Comma separated list of EAV codes                                                                      | List of attributes used for identity searches. ​                                                                                                                                                                                                        |
 +| idm.sec.reg.activationMode ​                 | REGISTRATION,​ ACTIVATION, HYBRID ​                                                                      | Sets mode for identity registration ​                                                                                                                                                                                                                   |
 +| idm.sec.reg.onlyActiveIdentities ​           | true/​false ​                                                                                            | This applies only in ACTIVATION mode. This property says, that only active identities are allowed to register. ​                                                                                                                                        |
 +| idm.sec.reg.changePasswordInIdM ​            | true/​false ​                                                                                            | If this property is set to true, then registration module will set password in IdM                                                                                                                                                                     |
 +| idm.sec.reg.changePasswordEveryWhere ​       | true/​false ​                                                                                            | If this property is set to true, then registration module will set password on all users accounts ​                                                                                                                                                     |
 +| idm.sec.reg.createEnabledIdentity ​          | true/​false ​                                                                                            | If true, then identity state will be enabled after creation. Note that this could be overwritten by HR processes. ​                                                                                                                                     |
 +| idm.sec.reg.createEnabledConract ​           | true/​false ​                                                                                            | If false, then identity contract will be disabled after its creation (after confirmation) ​                                                                                                                                                             |
 +| idm.sec.reg.enableContractAfteronfirmation ​ | true/​false ​                                                                                            | Determines, whether contract should be enabled after approval of registration ​                                                                                                                                                                         |
 +| idm.sec.reg.confirmedContractExterne ​       | true/​false ​                                                                                            | If true, then registered users contracts will be marked as externist ​                                                                                                                                                                                  |
 +
 +===== User registration =====
 +
 +{{ :​devel:​documentation:​registration_module.gif |}}
 +
 +===== Approve the registration =====
 +
 +{{ :​devel:​documentation:​registration_module_01.gif |}}
 +
 +====== Read more ======
 +[[devel:​documentation:​modules_reg:​versions|Registration module version]]
 +===== Admin tutorials =====
 +  * [[tutorial:​adm:​modules_reg| How to register to CzechIdM]]