/
Password Recovery

This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Password Recovery

Oct 24, 2017

This section describes the usage of the User Information Recovery APIs in WSO2 Identity Server. Using the API there are two ways to recover a lost/forgotten password, i.e., by using email notifications or secret questions. Additionally it is also possible to retrieve the username if forgotten. See the following topics for more information on how to do all this.

Recovery using notifications

WSO2 Identity Server supports password recovery by using email-based notifications. The following describes the configurations required in order to send email using the axis2 mail transport in the WSO2 Identity Server for password recovery.

To recover with notification:

  1. Enable the Identity Listener by setting the following property to true in the <IS_HOME>/repository/conf/identity/identity.xml file.

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

  2. Edit the identity­-mgt.properties file with the following configurations. This file is found in the <PRODUCT_HOME>/repository/conf/identity directory.

    Notification.Sending.Enable=true Notification.Expire.Time=3 Notification.Sending.Internally.Managed=true UserAccount.Recovery.Enable=true Captcha.Verification.Internally.Managed=false

    See the following table for descriptions of these configurations.

  3. Ensure that the email-­admin-­config.xml file has the following configurations. This file is found in the <PRODUCT_HOME>/repository/conf/email directory. Use the email format with the type “passwordReset”.

    <configuration type="passwordReset"> <targetEpr></targetEpr> <subject>Password Reset Notification</subject> <body> Hi {first-­name} We received a request to change the password on the {user-­name} account associated with this e­mail address. If you made this request, please click the link below to securely change your password: https://localhost:8443/InfoRecoverySample/infoRecover/verify?confirmation={confirmation-code}&amp;userstoredomain={userstore-domain}&amp;username={user-name}&amp;tenantdomain={tenant-domain} If clicking the link doesn't seem to work, you can copy and paste the link into your browser's address window. If you did not request to have your {user-­name} password reset, simply disregard this email and no changes to your account will be made. </body> <footer> Best Regards, WSO2 Carbon Team http://www.wso2.com </footer> <redirectPath></redirectPath> </configuration>

    The email sent to user includes the {confirmation-code}, which the Identity Server API caller needs to pass along with the user name.

  4. Edit the axis.xml file with the following configuration. This file is found in the <PRODUCT_HOME>/repository/conf/axis2/ directory. Uncomment the following in the file and provide the necessary email settings.

    <transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender"> <parameter name="mail.smtp.from">sampleemail@gmail.com</parameter> <parameter name="mail.smtp.user">sampleemail</parameter> <parameter name="mail.smtp.password">password</parameter> <parameter name="mail.smtp.host">smtp.gmail.com</parameter> <parameter name="mail.smtp.port">587</parameter> <parameter name="mail.smtp.starttls.enable">true</parameter> <parameter name="mail.smtp.auth">true</parameter> </transportSender>

Recovering the password with email notification can be achieved using the exposed UserInformationRecoveryService. The WSDL file for this service can be found in the following URL of your Identity Server installation: https://localhost:9443/services/UserInformationRecoveryService?wsdl.

The service security is implemented using Captcha and confirmation codes expire after a while. This makes the services secure and fails repeated attempts to access the same service. The sequence of calls that the calling application must do is as follows for email-based recovery:

  1. getCaptcha() -­ Generates a captcha.

  2. verifyUser() -­ Validates the captcha answer and username and returns a new key.

  3. sendRecoveryNotification() -­ Send an email notification with a confirmation code to the user. Need to provide the key from previous call.

  4. getCaptcha() ­- Generates a captcha when the user clicks on the URL.

  5. verifyConfirmationCode() -­ Validates the captcha answer and confirmation code. This returns a key.

  6. updatePassword() -­ Updates the password in the system. Need to provide the key from previous call, new password and returns the status of the update, true or false.

The flow of password recovery by email notification is as follows using the WSDL file (https://localhost:9443/services/UserInformationRecoveryService?wsdl). First you need to get the captcha using the getCaptcha() method. The captcha details returned should be passed along with the visible captcha answer and user name to verifyUser() which is for user verification. Upon successful verification, it will return a code. Then you need to call the sendRecoveryNotification() method to send the notification along with the code to the user. The generated email with the password reset link will be emailed to the user. Once the user clicks the reset link, the user should be directed to another captcha page for verification by calling getCaptcha(). The confirmation code must be verified along with the captcha answer by calling verifyConfirmationCode(). This will generate another code that must be passed to the updatePassword() method to update the password.

See Configuring Sample Application For Identity Management for a sample of how this works.

Recovery using challenge questions

The WSO2 Identity Server provides an alternative means of recovering passwords. This is by using challenge questions. So, 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. From the Main menu, click List under Claims.

  3. Click the WSO2 claim dialect (http://wso2.org/claims).

  4. You must select and configure three claim mappings. These are Challenge Question, Challenge Question1 and Challenge Question2.


    The following are the three claims necessary. For each claim URI below, there should be one claim mapping.

    • http://wso2.org/claims/challengeQuestionUris 

    • http://wso2.org/claims/challengeQuestion1 

    • http://wso2.org/claims/challengeQuestion2

  5. For the mapped attribute, provide any attribute that your underlying user store supports. This example keeps the defaults as they are. The three claims are set as ‘Supported by Default’ so that these attributes will appear in the user’s profile when viewing from the management console.

    The following table lists out how these claims are used.

    Now the required claim mappings for challenge questions feature are set.

The following are three ways to set up challenge questions for users.

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. You can 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. Log into the Identity Server as an admin.

  10. On the Main tab in the Management Console, click List under Users and Roles.

  11. Click Users. This link is only visible to users with the Admin role. 

  12. Click User Profile next to the user you created.

  13. You can see that the challenge question values are set for this user.

  14. Enter an email address and other required details for the user profile and click Update to save changes.

  15. Logout of the management console. 

  16. Sign out of the dashboard and click Forgot Password on the login screen. 

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

  18. Enter the answers to the challenge questions and click Submit. 

  19. Enter a new password and click Submit. You will receive a notification of successful password reset.