Password Recovery

This section guides you through setting up password recovery for users to recover a lost or forgotten password. There are two methods of password recovery:

Recovery using notifications

WSO2 Identity Server supports password recovery using email-based notifications. The flow of this method is as follows:

• The user initiates the password recovery flow by clicking on "Forgot Password" at the point of login. 
• The user enters the username and selects Recovery with Email.
• An email is sent to the user with a URL which directs the user to a screen where theycan enter a new password. 

Follow the steps given below to set up and try out password recovery with email notification. 

<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.mgt.IdentityMgtEventListener" orderId="50" enable="false"/>
<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.governance.listener.IdentityMgtEventListener" orderId="95" enable="true" />
<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.governance.listener.IdentityStoreEventListener" orderId="97" enable="true">

1. Configure the following email settings in the <IS_HOME>/repository/conf/output-event-adapters.xml file. 
   The email address configured here is the email account that will be used to send password recovery email notifications to users. 

   <adapterConfig type="email">
       <!-- Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust
           based authentication rather username/password authentication -->
       <property key="mail.smtp.from">abcd@gmail.com</property>
       <property key="mail.smtp.user">abcd</property>
       <property key="mail.smtp.password">xxxx</property>
       <property key="mail.smtp.host">smtp.gmail.com</property>
       <property key="mail.smtp.port">587</property>
       <property key="mail.smtp.starttls.enable">true</property>
       <property key="mail.smtp.auth">true</property>
       <!-- Thread Pool Related Properties -->
       <property key="minThread">8</property>
       <property key="maxThread">100</property>
       <property key="keepAliveTimeInMillis">20000</property>
       <property key="jobQueueSize">10000</property>
   </adapterConfig>

   Tip: The email template used to send this email notification is the PasswordReset template.

   You can edit and customize the email template. For more information on how to do this, see Customizing Automated Emails.

2. Start WSO2 Identity Server (WSO2 IS) and log in to the management console.
3. Click on Resident found under the Identity Providers section on the Main tab of the management console.

4. Expand the Account Management Policies tab, then the Account Recovery tab and select the Enable Notification Based Password Recovery. 
   For more information on the fields seen on this screen, see Account Recovery REST API. 

   

   Note

   If you apply the WUM update for WSO2 IS 5.7.0, released on the 2nd of October 2018, you can enable reCAPTCHA when you set up password recovery using notifications.

   You can deploy /wiki/spaces/updates/pages/16318500 into production only if you have a paid subscription. If you do not have a paid subscription, you can use this feature when the next version of WSO2 Identity Server is released.

   Select the Enable reCaptcha for Password Recovery checkbox to enable reCaptcha for password recovery flow. For more information, see Configuring reCaptcha for Password Recovery.

   

5. Notification Expiry Time can be configured to set a limit for the expiration of the notification sent. This is by default set to 1440 minutes (24 hours). 

6. To enable sending a confirmation email to the user's registered email address after the password reset, select the Notify when Recovery Success checkbox. 

   Tip: The email template used to send the confirmation email notification is the passwordResetSuccess template.

   You can edit and customize the email template. For more information on how to do this, see Customizing Automated Emails.

Try out recovery using notification

1. Create a user using the management console. Ensure that the user has login permissions. 
2. Edit the user profile and enter an email address for the user. The email notification for password recovery is sent to the email address given. 
3. Access the WSO2 Identity Server dashboard using the following link: https://localhost:<port_number>/dashboard.
4. Click Forgot Password. 

5. Enter the user's username, select Recover with Email, and then click Submit. 
   

   Note

   If you apply the WUM update released on the 2nd of October 2018 for WSO2 IS 5.7.0 and enable reCAPTCHA when you set up password recovery using notifications, you will see the following screen with the reCAPTCHA field when you click Forgot Password:

   

   Follow the steps below to recover the password:

   1. Enter the user name of the user that you created.
   2. Select Recover with Mail.
   3. Select I'm not a robot, and then click Submit. 
6. An email notification is sent to the user's email address. Click on the Reset Password button given on the email. 
   
7. Enter a new password and click Submit. 
   

Recovery using challenge questions

The WSO2 Identity Server provides an alternative means of recovering passwords. This is by using challenge questions. If users forget their password, they can recover it by answering challenge questions that were set up for their accounts.

Before setting this up, you must configure the required claims for this feature. To do this, do the following.

1. Enter your username and password to log on to the Management Console.
2. Click on Resident found under the Identity Providers section on the Main tab of the Management Console.

3. Expand the Account Management Policies tab, then the Account Recovery tab and select the Enable the Security Questions Based Password Recovery. 
   

   Note

   If you apply the WUM update for WSO2 IS 5.7.0, released on the 2nd of October 2018, you can enable reCAPTCHA when you set up password recovery using challenge questions.

   You can deploy a /wiki/spaces/updates/pages/16318500 into production only if you have a paid subscription. If you do not have a paid subscription, you can use this feature when the next version of WSO2 Identity Server is released.

   When you apply the WUM update, the Account Recovery screen will be as follows:

   

   Follow the steps below to prompt users for reCAPTCHA at the time of password recovery using challenge questions:

   1. Set up reCAPTCHA with WSO2 Identity Server. For detailed instructions, see Setting Up reCAPTCHA.
   2. Select Enable Security Question Based Password Recovery and Enable reCaptcha for Password Recovery.

4. Configure the required number of questions in the Number of Questions Required for Password Recovery. 
   Optionally, select the Notify when Questions Based Recovery Starts checkbox to send an email notification to the user when the question based recovery starts. 

You can set up challenge questions for users in one of the following ways: 

Using the management console

To set up challenge questions or to manage the questions with different locales (languages), see Managing Challenge Questions. 

Using the end user dashboard

To try this out, first create a user in the Identity Server.

1. On the Main tab in the Management Console, click Add under Users and Roles.
   
2. Click Users. This link is only visible to users with the Admin role. 
   

3. Click Add New User.
   

4. Log out of the Identity Server.
5. The URL for accessing dashboard is the following if the hostname is localhost and the Identity Server is running on port 9443: https://localhost:9443/dashboard/. Click this link to access the dashboard and log in using the credentials of the user you just created.
   
   
6. Click the View Details button under the Account Recovery section in the end user dashboard.
    
7. Set challenge questions for the user account. There are two sets of challenge questions by default. You can pick one question for each set and give an answer for the question.
   
   
8. Click Update.
9. Sign out of the dashboard and click Forgot Password on the login screen. 
   

10. Enter the username and select Recover with Security Questions. Click Submit. 

    Tip: If you have configured WSO2 IS to use email address as the username, enter the username in the format of "john@foo.com". If the user is in the super tenant, this is in the format of "john@foo.com@carbon.super". If the user is in the tenant bar.com, the format you must enter is "john@foo.com@bar.com".

    

    
    

    Note

    If you apply the WUM update released on the 2nd of October 2018 for WSO2 IS 5.7.0 and enable reCAPTCHA when you set up password recovery using challenge questions, you will see the following screen with the reCAPTCHA field when you click Forgot Password:

    

    Follow the steps below to recover the password:

    1. Enter the user name of the user that you created.
    2. Select Recover with Security Questions.
    3. Select I'm not a robot, and then click Submit. 

    
    

11. Enter the answers to the challenge questions and click Submit.
    
12. Enter a new password and click Submit. You will receive a notification of successful password reset. 

Password recovery using multiple claims

This feature allows the users to recover their password using claims other than the username. The service caller can define any number of claims that should be used in the user details verification. The claims other than the username claim shown in the password recovery form will be the same claims that will be shown in the username recovery form.

To enable multi-claim passowrd recovery do the following.

1. Log in to the Management Console and go to Claims > Add > Add Local Claim. 

2. Add the Preferred Channel Claim as a local claim: http://wso2.org/claims/identity/preferredChannel.

   The claim URI is case sensitive. 

   NOTE: Not configuring the above claim will give errors.

3. Go to <IS_HOME>/repository/deployment/server/webapps/accountrecoveryendpoint/WEB-INF/web.xml and change the existing jsp file of the recoverpassword.do servelet from password-recovery.jsp to point to password-recovery-with-claims.jsp.

   <servlet>
   	<servlet-name>recoverpassword.do</servlet-name>
   	<jsp-file>/password-recovery-with-claims.jsp</jsp-file>
   </servlet>

Try out multi-claim password recovery

1. Access the WSO2 Identity Server dashboard using the following link: https://localhost:<port_number>/dashboard.
2. Click Forgot Password. 
3. You will now be directed to the following page instead of the default password recovery page shown in above steps.
4. Provide one or more user attributes and enter Submit.

5. Select a recovery option and enter Submit. The rest of the flow will be the same as using password recovery with username as shown above.

<Context>/api/users/v1/recovery/</Context>