This documentation is for WSO2 Identity Server 5.4.0 . View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

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
  • Recovery using challenge questions

This document guides you on setting up recovery using notifications. For instructions on recovery using challenge questions, see Password Recovery Using Challenge Questions

From 5.3.0 onwards there is a new implementation for identity management features. The steps given below in this document follows the new implemenation which is the recommended approach for password recovery.

Alternatively, to see steps on how to enable this identity management feature using the old implementation, see Password Recovery documentation in WSO2 IS 5.2.0. The old implementation has been retained within the WSO2 IS pack for backward compatitbility and can still be used if required.

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 they can enter a new password. 

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

Before you begin

Ensure that the "IdentityMgtEventListener" with the orderId=50 is set to false and that the Identity Listeners with orderId=95  and orderId=97 are set 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="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">[email protected]</property>
        <property key="mail.smtp.user">abcd</property>
        <property key="mail.smtp.password">xxxx</property>
        <property key=""></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>

    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 the WSO2 Identity Server 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 checkbox. 
    For more information on the fields seen on this screen, see Account Recovery REST API

  5. 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.

If you are using a Google mail account, note that Google has restricted third-party apps and less secure apps from sending emails by default. Therefore, you need to configure your account to disable this restriction, as WSO2 IS acts as a third-party application when sending emails to confirm user registrations or notification for password reset WSO2 IS.

 Click here for more information.

Follow the steps given below to enable your Google mail account to provide access to third-party applications.

  1. Navigate to
  2. Click Signing in to Google on the left menu and make sure that the 2-step Verification is disabled or off.
  3. Click Connected apps and sites on the left menu and enable Allow less secure apps.

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 the Forgot Password link. 
  5. Enter the user's username and select Recover with Email. 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
  • For information on the REST APIs for password recovery, see the swagger docs on Account Recovery REST APIs.

  • By default, the claim values of the identity claims used in this feature are stored in the JDBC datasource configured in the identity.xml file. See Configuring Claims for more information on how to store the claim values in the user store.
  • No labels