<securityPolicy>
...
<authentication>
<modules>
...
<archetypeSelection>
<identifier>archetypeSelection</identifier>
<archetypeSelection>
<archetypeRef oid="612c147c-1ef7-4be9-9085-a1cb6ca8515e"/> <!-- Reference to Applicant archetype -->
<archetypeRef oid="5bd3f6b4-e328-4f6e-976a-7b5b0c48346d"/> <!-- Reference to Student archetype -->
<archetypeRef oid="9e105fbc-38e2-4de9-9b93-58bce2f2995a"/> <!-- Reference to Teacher archetype -->
</archetypeSelection>
<allowUndefinedArchetype>true</allowUndefinedArchetype>
</archetypeSelection>
...
</modules>Identity recovery
Identity recovery feature brings the possibility to recover user’s data in case they were forgotten. User can recover their login name or other data depending on the configuration.
This functionality can be used in case when the user needs to log in to the system, but they forgot their login and password. To go through reset password flow, the user definitely will need their name or other identifier to be authorized for changing a password. Therefore, Identity recovery feature can be configured to help the user to recover their identity data to proceed then with password recovery or login process.
Identity recovery flow description
To recover the identity, the system tries to find out at first, if there any archetype the user belongs to. This step narrows the list of possible identities candidates. Also specifying the archetype brings the appropriate security policy and further configuration for the next steps. For these purposes Archetype selection module is used. It defines a list of archetypes among which the user can make a choice. If the user cannot choose some definite archetype, the flow still can be continued with the undefined archetype if this option is configured in the Archetype selection module.
After the archetype is selected by user (or undefined option is chosen), the user goes through correlation steps. For these purposes Correlation module is used. While going through this module the user should provide their data. MidPoint searches for the user’s account basing on the entered data. The search is processed with the help of correlation mechanism and as a result one or multiple users' accounts can be found. Correlation module defines the list of correlators which are responsible for the search. The correlators are processed one by one and correlation module can be finished after any of them if the correlation result has already found a specified user’s account (in this case the found account’s data will be displayed on the screen). Otherwise, all correlators are processed and the results are shown on the screen. Correlation module configuration allows to restrict the number of the accounts which can be found by the correlators. If the correlation result contains more accounts than it’s allowed, correlation module will end up with an error. If no limitation is set, all found accounts will be displayed to the user.
Identity recovery configuration
To make Identity recovery functionality working 3 basic authentication sections should be configured: modules, sequence and flow. Please, look at flexible authentication documentation to learn more about authentication configuration.
More configuration samples can be found within schrodinger project which covers the functionality with several GUI tests.
Archetype selection and Correlation authentication modules
Archetype selection and Correlation authentication modules are configured in the modules part of the authentication section in the security policy object.
Information about Archetype selection and Correlation authentication modules can be found in the flexible authentication configuration.
The following Archetype selection module gives the possibility to select among 3 archetypes: Student, Applicant and Teacher. Undefined archetype option is also allowed.
Archetype selection module configuration
Correlation module defines correlators identifiers and their order.
Correlator identifier refers to the name attribute of the correlators element which is defined in correlation part of object template.
The maximum number of the users to be found is set within candidateLimit element.
Correlation module requires all correlation items to be specified with a value.
Correlation module configuration
<securityPolicy>
...
<authentication>
<modules>
...
<correlation>
<identifier>correlationModule</identifier>
<description>Correlation module defines which correlators are used for identity recovery flow. Correlator identifier should match correlator name attribute value defined in the object template.</description>
<correlator>
<correlatorIdentifier>identity-recovery-1</correlatorIdentifier>
<order>1</order>
</correlator>
<correlator>
<correlatorIdentifier>identity-recovery-2</correlatorIdentifier>
<order>2</order>
</correlator>
<correlator>
<correlatorIdentifier>identity-recovery-3</correlatorIdentifier>
<order>3</order>
</correlator>
<options>
<candidateLimit>3</candidateLimit>
</options>
</correlation>
...
</modules>Identity recovery authentication sequence
Identity recovery authentication sequence is configured within sequence element in the authentication section of the security policy object.
Sequence specifies the modules which are processed during Identity recovery flow (Archetype selection and Correlation modules have to be defined there).
Identity recovery sequence
<securityPolicy>
...
<authentication>
...
<sequence>
<identifier>identity-recovery-sequence</identifier>
<channel>
<channelId>http://midpoint.evolveum.com/xml/ns/public/common/channels-3#identityRecovery</channelId>
<default>true</default>
<urlSuffix>identityRecovery</urlSuffix>
</channel>
<module>
<identifier>archetypeSelection</identifier>
<order>1</order>
<necessity>requisite</necessity>
</module>
<module>
<identifier>correlationModule</identifier>
<order>2</order>
<necessity>requisite</necessity>
</module>
</sequence>
...Identity recovery flow
Identity recovery flow is configured just straight in the security policy object.
authenticationSequenceIdentifier element points to the authentication sequence which should be used during this flow.
The list of items to be displayed to the user on the final screen can be configured with the help of multivalue itemToDisplay element.
However, this is not obligatory to configure itemToDisplay.
If none is specified, name attribute of the recovered identity object will be displayed on the final screen.
Also, Identity recovery link text (displayed on the Login panel) can be configured within display element.
Identity recovery flow
<securityPolicy>
...
<identityRecovery>
<identifier>identity-recovery</identifier>
<authenticationSequenceIdentifier>identity-recovery-sequence</authenticationSequenceIdentifier>
<itemToDisplay>emailAddress</itemToDisplay>
<itemToDisplay>fullName</itemToDisplay>
<display>
<label>Forgot your login name?</label>
</display>
</identityRecovery>
...Another objects
To build up full configuration of the Identity recovery functionality, some other objects also should be present in the system. In this section of the document the full chain of the configuration objects is described.
Archetype objects
As it was mentioned above, Archetype selection authentication module has a list of references to archetype objects.
Archetype object is responsible not only for defining user’s role in the system but for specifying which security policy and correlation configuration should be used.
This means that after archetype is selected, the system knows the particular security policy which is used to continue the flow.
Also, the system knows object template which contains a definition of the correlators which will be used by the flow as well.
In case Undefined archetype option is selected by the user during Archetype selection step, default security policy (referenced from system configuration object) and default object template (also referenced from system configuration object, in defaultObjectPolicyConfiguration section) are used.
Archetype object example
<archetype>
<name>Student</name>
<archetypePolicy>
<objectTemplateRef oid="object_template_oid"/>
...
</archetypePolicy>
<securityPolicyRef oid="student_security_policy_oid" />
</archetype>Security policy objects
Each archetype specified in the Archetype selection authentication module, has to reference security policy object. Security policy referenced from archetype can extend default security policy with the specific configuration. In that way different behavior during Identity recovery flow can be configured for different archetypes. To learn more about how security policy can be extended, please, read security policy merging documentation.
For example, archetype security policy can extend Correlation authentication module with further correlators.
Correlation module in the default security policy
<correlation>
<identifier>correlationModule</identifier>
<correlator>
<correlatorIdentifier>identity-recovery-1</correlatorIdentifier>
<order>1</order>
</correlator>
</correlation>Correlation module in the Student archetype security policy
<correlation>
<identifier>correlationModule</identifier>
<correlator>
<correlatorIdentifier>identity-recovery-1</correlatorIdentifier>
<order>10</order>
</correlator>
<correlator>
<correlatorIdentifier>identity-recovery-2</correlatorIdentifier>
<order>20</order>
</correlator>
<correlator>
<correlatorIdentifier>identity-recovery-3</correlatorIdentifier>
<order>30</order>
</correlator>
</correlation>Another example is extending identityRecovery section with the list of the items which are to be displayed on the final screen
Identity recovery specification in the default security policy
<identityRecovery>
<identifier>identity-recovery</identifier>
<authenticationSequenceIdentifier>identity-recovery-sequence</authenticationSequenceIdentifier>
</identityRecovery>Identity recovery specification in Student archetype security policy
<identityRecovery>
<identifier>identity-recovery</identifier>
<authenticationSequenceIdentifier>identity-recovery-sequence</authenticationSequenceIdentifier>
<itemToDisplay>emailAddress</itemToDisplay>
<itemToDisplay>nickName</itemToDisplay>
</identityRecovery>Object template objects
Each archetype specified in the Archetype selection authentication module, has to reference object template object.
Object template is responsible for correlators definition.
The correlators are used by the Correlation authentication module to find the account (or possible accounts) of the user.
Each correlator which is expected to be used by the Correlation module, has to define use element with identityRecovery value.
Object template example with correlation definition
<objectTemplate>
....
<correlation>
<correlators>
<name>identity-recovery-1</name>
<items>
<name>nationalId</name>
<item>
<ref>extension/nationalId</ref>
</item>
</items>
<use>identityRecovery</use>
</correlators>
<correlators>
<name>identity-recovery-2</name>
<items>
<item>
<ref>givenName</ref>
</item>
<item>
<ref>familyName</ref>
</item>
</items>
<use>identityRecovery</use>
</correlators>
</correlation>
</objectTemplate>Found identities step description
The last step of the Identity recovery flow - Found identities - contains some possibilities which can lead a user to further flows.
No matter, if any identity was found or not, the user can restart the flow again with the help of Restart the flow button.
Figure 1. Restart the flow button.
If user finds among the found identities the one he needs, they can confirm the identity. In this case they are redirected to the Login page with the prefilled Username field.
Figure 2. Confirm my identity button.
Found identities step can also contain a link to the self registration page in case registration flow is configured in the security policy. The data which were entered by the user during Identity recovery flow will be used then to prefill self registration form. If self registration flow is configured in the default security policy, the link to the registration page will be visible for all types of users. There is also a possibility to configure self registration flow only for the specified user’s group, for that self registration flow should be configured within archetype security policy (security policy referenced from the archetype). Please, mention that in case self registration flow is configured within archetype security policy, authentication sequence and authentication modules used by self registration flow should be defined in the global (default) security policy due to the current implementation. More information about self registration flow configuration you can find by the link.
Identity recovery flow example
-
User opens Login page. Recover your identity link is present. Note that link text is configurable, therefore it can be different.
Figure 3. Login page with Recover your identity link.
-
After the link is clicked, Archetype selection step is opened. The user makes a choice on the Archetype selection panel and clicks Send button.
Figure 4. Archetype selection step.
-
The user is redirected to the Correlation module. All fields are to be filled in.
Figure 5. Correlation step, first correlator.
-
If the first correlator processing doesn’t result with a single suitable user account, next correlator panel is displayed.
Figure 6. Correlation step, second correlator.
-
After data are sent and the identity is found, result panel is shown.
Figure 7. Found identities panel.
Identity recovery auditing
Identity recovery flow is audited in order to analyze identity recovery attempts. Taking in account that the result of the successful identity recovery flow is displaying of the identity(es) data, we want to keep the information about which identities were displayed. Therefore, after identity recovery flow is produced, audit record with appears in Audit log Viewer with Information Disclosure event type and Modify operation (event though no modify operation wasn’t produced for real). The initiator of the information disclosure event is Identity recovery service which is initial object of the Midpoint created for Identity recovery flow in order to be principal object during this flow. In case some identities were found and displayed, found object names are displayed on the Audit Log Details page.
Was this page helpful?
YES
NO
Thanks for your feedback