Account Recovery configurations in WSO2 Identity Server

Figure 1 (

In Identity and Access Management, Account Recovery is one of the most important use cases that we need to explore on. Due to the rapid growth in digital transformation and technology, these days people have multiple accounts in multiple websites. Hence, there is a high probability of the users loosing the access to their digital accounts due to loosing credentials. Account recovery is a process designed to get back to your accounts when you don’t have enough information to access your accounts. To cater this requirement, WSO2 Identity Server (IS) has various account recovery options which can be provided for your users.

The purpose of this blog is to gather the recovery options into one place, so that it will be easy for an application administrator to choose the options they need. Further, there is a considerably long list of configurations available for account recovery in the WSO2 IS. Hence, this blog describes all of those configurations which are listed under Account Recovery in the management console of the identity server (Figure 2) and the specific configurations needed for each use case.

Figure 2: Account recovery configurations in WSO2 Identity Server

There are two major use cases under account recovery, which can be identified as password recovery and username recovery.

Password Recovery

This is the most common use case which is commonly known as “forgot password” option. When users forget their passwords, there are several options to recover their accounts as follows.

  1. Send password reset link to the registered email — when the user selects the “Recover with Mail” option, he will receive an email with the password reset link which can be used to set a new password.
  2. Use security questions to reset the password — when the user selects the “Recover with Security Questions” option, he will be prompted with security questions and the user needs to answer them correctly. If the answers are correct, the user will be able to reset the password. These security questions should be configured in the user profile beforehand in order to use this option.
  3. Use a one-time password (OTP) to reset the password — in this method, an OTP is sent to the registered phone number and that can be used to reset the password. This is currently not supported via the My Account of the WSO2 Identity Server, but available via Account Recovery REST APIs. Refer this for more information.

Username Recovery

This is the use case known as “Forgot Username”. It is mostly used in websites which needs a username to access the account that is not similar to the email address. This is done by identifying the user account by requesting user details such as email, first name and last name. If those details are verified successfully and identified the account, the username will be sent via email.

To achieve each of those use cases, you have to configure the relevant options from the configurations listed under Account Recovery in the management console. Before that, following prerequisites should be satisfied.


  1. Download the WSO2 Identity Server from here.
  2. Configure the email sending module in the WSO2 Identity Server as explained here.
  3. Start the WSO2 Identity Server, log into the ​ management console​ using “admin” as both the username and the password.
  4. Create a user.
  • On the ​Main​ tab click on Users and Roles​ -> ​Add.
  • Click ​ Add New User​.
  • Create a new user by giving a username and a password.
  • Go to User Profile and add an email address.

Assign login permissions to the created user.

  • Click the View Roles option of the created user.
  • Click Permissions. Select Login and click Update.

5. Go to myaccount and log in with the created user credentials. Go to Security tab and Under Account Recovery, click + to add security questions. After that sign out from the account. (Setting up the security questions can also be done using the management console as explained here)

6. Set up recaptcha in the Identity Server as explained here.

Since now you have an understanding on account recovery functionalities available and you are done with the prerequisites, configuring above recovery options in the identity server will be just a matter of choosing relevant configurations. Along with that, I will describe each account recovery configuration we have in the WSO2 Identity Server.

Password Recovery via mail

  • Since you have already configured the email sending module, the only thing remaining to do is enabling notification based password recovery. For that, go to Main >Identity Providers>​ ​ Resident > Account Management Policies> Account Recovery. Select the Enable Notification Based Password Recovery check box and click Update.
  • You can add an additional layer of security by selecting the option Enable reCaptcha for password recovery. A reCaptcha can determine if the system is dealing with a human or an automation.
  • By selecting the Enable Auto Login After Password Reset checkbox, the user will be logged into the account after the password reset.
  • If the user wants to receive a confirmation email once password reset is done, select the Notify when Recovery Success checkbox.
  • You can specify the recovery link validity period by configuring Recovery link expiry time.
  • If you want to redirect the user to a particular location after the password recovery request is completed, you can add a regular expression for the Recovery callback URL regex that will match to the redirect URL.

Above are the all configurations related to password recovery via mail. To test out the scenario, go to myaccount and click forgot password. Enter the username, select Recover with Mail and click Submit. The email address added to the user profile should receive an email with a link to reset the password.

Password Recovery via Security Questions

  • This can be achieved by selecting Security question based password recovery checkbox in Main >Identity Providers>​ ​ Resident > Account Management Policies> Account Recovery. Required number of questions can be configured using the configuration Number of questions required for password recovery.
  • To enable recaptcha, select Enable reCaptcha for Security Question Based Password Recovery and set Max failed attempts for reCaptcha. (Account locking should be enabled using Main >Identity Providers>​ ​ Resident > Login Attempts Security> Account Lock). Then recaptcha will be prompted after the specified number of failed attempts for the security questions.
  • Similar to the above password recovery via mail method, Enable reCaptcha for password recovery, Enable Auto Login After Password Reset, Notify when Recovery Success and Recovery callback URL regex configurations can be used for the password recovery via security questions option as well.

After setting up the above configurations, go to myaccount and click forgot password. Enter the username, select Recover with Security Questions and click Submit. You will be prompted to enter the answers for some security questions you set at the beginning depending on the number of questions you specified for password recovery. Once you answer the questions correctly, you will be prompted with the reset password form.

Other than the configurations mentioned for this password recovery option, there are four more configurations related to security questions under account recovery as follows.

Enable forced challenge questions — If this is enabled, users should provide answers to the security questions during sign in

Minimum Number of Forced Challenge Questions to be Answered — Users should provide answers to the security questions during sign in if they have answered lesser than this value

Challenge question answer regex — If you want to add a regex pattern for the answers of the security questions, you can specify it here

Enforce challenge question answer uniqueness — if this is enabled, it doesn’t allow to add the same answer for multiple questions

Username Recovery

  • Username recovery can be enabled by selecting the configurations Username recovery and Manage notifications sending internally.
  • For this option, we can enable recaptcha by selecting Enable reCaptcha for username recovery configuration.

After setting up these configurations, click forgot username in myaccount. You will be prompted with a form to enter user details to recover the username. If the user details are verified successfully, an email with the username will be received.

With the above use cases, all the configurations available under account recovery in the WSO2 Identity Server are covered. Hope this blog helped to have an overall understanding on account recovery configurations available in IS currently. Stay tuned for more WSO2 IS features!



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Rashmini Naranpanawa

Rashmini Naranpanawa

Software Engineer @WSO2 | Graduate @Department of Computer Science and Engineering, University of Moratuwa