### Overview
This guide covers the process for enabling the Account Recovery features within the Ellucian Ethos Identity (EEI) product. One thing to be noted is that EEI is based off of the WSO2 open-sourced Identity Server platform. Documentation is readily available and open to everyone online. All the topics found in this guide were sourced from it.

- [Full example code](https://github.com/EricCanull/accountrecoveryendpoint)

:::info
:warning: **Alert:** Prerequisites prior to starting
1. The user specified in the LDAP connection configuration must have permissions in LDAP/Active Directory to perform password changes on behalf of other users and write changes to attributes such as the password timestamp value and locked out status.

2. The connection between Ellucian Ethos Identity and LDAP or Active Directory must be over a secure channel.
:::

### LDAP configuration
The LDAP Connection type must be read/write in order for EEI to be permitted to modify the password, timestamp and account locked attributes.

Refer to the online documentation or Ellucian EEI setup documentation for information regarding how to add a read/write LDAP connection.
https://docs.wso2.com/display/IS580/Setting+Up+An+LDAP+User+Store


### Password Policy Authenticator

#### Deploying Password Policy artifacts
Download the Password Policy Authenticator and artifacts from the WSO2 connector store. (To download the authenticator, go to https://store.wso2.com/store/assets/isconnector/passwordpolicy)

Add the following lines to the identity-event.properties file in the following directory: <IS_HOME>/repository/conf/identity/.

module.name.13=passwordExpiry
passwordExpiry.subscription.1=POST_UPDATE_CREDENTIAL
passwordExpiry.subscription.2=POST_UPDATE_CREDENTIAL_BY_ADMIN
passwordExpiry.subscription.3=POST_ADD_USER
passwordExpiry.passwordExpiryInDays=30
passwordExpiry.enableDataPublishing=false
passwordExpiry.priorReminderTimeInDays=0

The value of **xx** in **module.name.xx** should be decided based on the highest module number that is already available in the identity-event.properties file. For example, if the last module number mentioned in the file is **module.name.11**, the above entry should be renamed as **module.name.12=passwordExpiry**.

Place the authentication **pwd-reset.jsp** file into the <IS_HOME>/repository/deployment/server/webapps/authenticationendpoint directory.

Place the **authenticator.jar** file (org.wso2.carbon.extension.identity.authenticator.passwordpolicy.connector-1.0.3.jar) into the directory <IS_HOME>/repository/components/dropins.

Edit the **identity-mgt.properties** found in the <IS_HOME>/repository/conf/identity directory and **add** the following property. This value must be an integer.

:::info
:bulb: **Hint:** If not added to the file, by default, the password reset time is 30 days.
:::

#### Add claim mapping
A claim is a piece of information about a particular subject. It can be anything that the subject is owned by or associated with, such as name, group, preferences, etc. In this instance, the claim in question is lastPasswordChangedTimestamp and this needs to be linked to a claim that is local to Identity Server. This claim is required because the Identity Server needs to know if the password is expired or not for this flow to work. 

:::info
:warning: **Warning:** when using an LDAP connection, the mapped attribute must be mapped to the corresponding timestamp attribute in the Active Directory. 
:::

Navigate to the Identity section under the Main tab of the management console.

Click **Add** under Claims and then click **Add Local Claim**.

![Add Local Claim](https://i.imgur.com/Jrc2T1E.png)

#### Reference the claim values in the table below.   

<table>
    <tr>
        <td>Claim Uri:</td>
        <td>http://wso2.org/claims/lastPasswordChangedTimestamp</td>
    </tr>
    <tr>
        <td>Display Name:</td>
        <td>Password Change Time</td>
    </tr>
    <tr>
        <td>Description:</td>
        <td>Password Change Time</td>
    </tr>
    <tr>
        <td>Mapped Attribute:</td>
        <td>[MatchingActiveDirectoryTimestamp]</td>
    </tr>
    <tr>
        <td>Read only:</td>
        <td>Checked</td>
    </tr>
</table>

<br>

:::info
:bulb: **Hint:** When testing, uncheck the “Read only” option and check the “Supported by Default” option.
::: 



#### Set Password Reset Enforcer (Authentication Step)
For testing, open any service provider settings. In production, this will have to be done for all Service Providers.

Go to Local and Outbound Authentication Configuration section.
Select the Advanced configuration radio button option .
Add the basic authentication as first step and password-reset-enforcer authentication as second step.

:::info
:bulb: **Hint:**The Use attributes from this step option is unchecked when the second step is added and selected.
:::

![Advanced Configuration](https://i.imgur.com/QZqfJJf.png)


#### Testing the sample
To test the sample, the password needs to be expired. 
- Select "Supported by Default" checkbox in the lastPasswordChangedTimestamp  that has the  http://wso2.org/claims/lastPasswordChangedTimestamp claim.

:::info
:warning: **Warning:** In a production environment, using an LDAP,, do not select the "Supported by Default" checkbox in the lastPasswordChangedTimestamp claim settings.
:::

Select “Supported by Default” on Password Change Time claim

Enter a date and time of the past for the Password Changed Time field. Make sure to provide the value in the Epoch format.

:::info
:bulb: **Hint:** WSO2 Identity Server does not consider timestamp value “0” as an expired password, however leaving the field blank will trigger a password change.
:::

Attempt to login. If successful, you should see the change password prompt as shown below.

:::info
![Password Prompt](https://i.imgur.com/z0RoDA4.png)
:::

### Authentication Recovery Endpoint
To turn on username and password recovery features, please complete the steps in the links below first.  Here we will be focusing on the pages that need to be customized.
- https://docs.wso2.com/display/IS570/Username+Recovery
- https://docs.wso2.com/display/IS570/Password+Recovery

#### Using custom claims for username recovery
The default attributes to validate a forgot username request are Name, Email, and Tenant Domain. These should be changed in order to match current IA policy requirements.  In the following example, I’m changing the requested attributes to be Email, Last 4 SSN, and DOB to satisfy our local requirements.

Review the example [username-recovery.jsp](https://github.com/EricCanull/accountrecoveryendpoint/blob/master/username-recovery.jsp)

Navigate to the /repository/deployment/server/webapps/accountrecoveryendpoint directory and open the username-recovery.jsp 

Take a look at the input fields. You will notice the name value is connected to a specific claim URI. 

<input id="email" type="email" name="http://wso2.org/claims/emailaddress"
<input id="ssn" type="ssn" name="http://wso2.org/claims/ssn"
<input id="birth-day" type="date" name="http://wso2.org/claims/dob"

Go ahead and create the claims to be used for username recovery.  

Ensure to check the “Supported by Default” option for any claim that will be used for this process. 

For recovery purposes, ensure to map the email claim to a secondary email address, and not the primary.  

Use the Regular Expression field to help standardize formatting and value types.
Last 4 of SSN is [0-9]{4}

Use the example [username-recovery.jsp](https://github.com/EricCanull/accountrecoveryendpoint/blob/master/username-recovery.jsp) to see how to setup the jsp code to meet the new input form requirements. If you see the error.jsp or cannot access the username recovery link on the main login page then it is likely you need to update the jsp to satisfy your input form requirements.  

If necessary, also add validation to the form using HTML5 by specifying the input is required and matches a pattern.  I’ve chosen to also add JQuery to validate as a back-up for compatibility for older browsers.

<script>
$(document).ready(function () {
$("#recoverDetailsForm").submit(function (e) {
var errorMessage = $("#error-msg");
errorMessage.hide();
<% if (isSocialInClaims){ %> // notice the JSP code here.
var ssn = $("#ssn").val();
if (!ssn.match('[0-9]{4}')) {
errorMessage.text("SSN must be 4 digits.");
errorMessage.show();
$("html, body").animate({
scrollTop: errorMessage.offset().top
}, 'slow');
return false;
}
<% } %>
<% if (isBirthDayInClaims){ %> // notice the JSP code here
var birthday = $("#birth-day").val();
if (birthday == '') {
errorMessage.text("Please enter Date of Birth.");
errorMessage.show();
$("html, body").animate({
scrollTop: errorMessage.offset().top
}, 'slow');
return false;
}
<% } %>
<% if(reCaptchaEnabled) { %> // notice the JSP code here.
var reCaptchaResponse = $("[name='g-recaptcha-response']")[0].value;
if (reCaptchaResponse.trim() == '') {
errorMessage.text("Please select reCaptcha.");
errorMessage.show();
$("html, body").animate({
scrollTop: errorMessage.offset().top
}, 'slow');
return false;
}
<% } %>
return true;
});
});
</script>

Secondary email used for recovery must be pre-established and chosen by the user.

### Claim Mapping
### Enable Challenge Questions
### Email-Based-Recovery and email notifications

### Documents used for recovery management
- **accountrecoveryendpoint**
    -- challenge-question-view.jsp
    -- error.jsp
    -- password-reset.jsp
    -- password-reset-complete.jsp
    -- password-recovery.jsp
    -- recovery.jsp
    -- username-recovery.jsp
    
- **authenticationendpoint**	
    -- pwd-reset.jsp
    -- tamusa.min.css 	<your_custom.css> 
    
- **Email Templates**
    -- AccountLocked.html
    -- AccountIdRecovery.html
    -- InitiateRecovery.html
    -- PasswordResetSuccess.html
    -- PasswordReset.html

Add / Enable claims – For username recovery
dob:  http://wso2.org/claims/dob
last 4 ssn: http://wso2.org/claims/ssn


Setup Recovery Notifications
https://docs.wso2.com/display/IS530/Password+Recovery
Email template HTML Example