Reissue Existing Password Recovery Confirmation Code in Followed Recovery or Resend Requests

Shan Chathusanda Jayathilaka
5 min readMay 29, 2021

Hi guys, today we are going to discuss about a new feature which will be released for the public distribution of WSO2 Identity Server 5.12.0 soon. This feature was developed to overcome the following scenario.

  1. User requests a password recovery.
  2. WSO2 Identity Server publishes an email which contains the link to recover the password. This link contains a confirmation code and other details.
  3. The email client is experiencing a delay and the email will be queued.
  4. User waits few minutes to receive the email and if the email is not received, the user will again trigger a recovery flow of a recovery resend flow.
  5. Now IS will check whether there are any confirmation codes already issued to the user. If so those previous confirmation codes will be revoked and a new email will be published with a new confirmation code.
  6. The second email is also queued in the email client since the delay.
  7. Meanwhile the email which was published from the step 2 can be received to the user.
  8. User will try to recover the password from that link but the user is unable to recover since the confirmation code in that email was already revoked/expired because of the second request.
  9. This can be happen again and again based on the delay of the email client.

You can refer the following diagram for more understanding of the above flow.

This scenario can be happen for anyone. So we introduced a new way to handle this scenario (Pointed below)for the Notification based password recovery flow.

  1. WSO2 Identity Server receives a password recovery request.
  2. Checks whether the corresponding user already has a confirmation code.
  3. If so checks whether the time duration between this request and the previous request is inside the pre-configured time period (We added a configuration to keep a time period which can be configured).
  4. If that is also true, in this request also WSO2 Identity Server is sending the same confirmation code with the email to the corresponding user without revoking it.

In this scenario user will get the same confirmation code within a time period and the user can recover the password smoothly.

This feature is already shipped with the latest wum update of WSO2 Identity Server 5.10.0 and will be available in the public distribution from WSO2 Identity Server 5.12.0 version.

Let’s move to the configurations.

First you need a WSO2 Identity server latest pack. Still the public distribution is not released you can download the latest milestone release. I am using the
5.12.0-m18 version in this chapter. Now open the deployment.toml file located in <IS_HOME>/repository/conf directory and add the following configurations.

Configurations are explained below.

  • recovery_code_validity : Contains the time that the recovery confirmation code is valid in minutes.
  • resend_code_validity : Contains the time that the resend recovery confirmation code is valid in minutes.
  • confirmation_code_tolerance_period : Within this time period the existing recovery confirmation link will be sent to the user. This value should be less than recovery_code_validity and resend_code_validity. Otherwise internally this value will be set to 0 and it will behave in the default way.

Now you need to add the email client configurations as described in here and start the server. After starting the server login to the Management Console by using username and password as admin. Go to the Resident IDP in Identity Providers section -> Account Management -> Account Recovery and enable Notification based password recovery.

Next create a user and fill the required fields for that user.

Now you have successfully completed the configurations. Let’s test this feature.

Here you have two ways to check this feature. First one is from the myaccount login UI.

  • Go to https://localhost:9443/myaccount
  • Click on Forgot password?
  • You will be redirected to a page where you will need to enter the username. Enter the username of the user and click on Submit.
  • After successfully sent the email, the following message will be shown to the user.
  • Login to the user’s email address and check the confirmation code in the password recovery link of the email with the title Password Reset.
  • Now again to the same process and check the confirmation codes of both emails. They will be the same. Now you can use any of the previous password recovery link for the password recovery.

The confirmation code in the recovery URL will be like the following.

Second way to test is from the APIs. In APIs there are two versions for Password recovery. They are V0.9 and V1.0.

In V0.9 for password recovery send you can user the API in here and you will receive an email with the confirmation code. If you want to resend the recovery email you can use the following curl or this.

curl -X POST -H “Authorization: Basic <Base64Encoded_username:password>” -H “Content-Type: application/json” -d ‘{“user”:{“username”: “<username>”,”realm”: “<user_store_name>”},”properties”: [{“key”: “RecoveryScenario”,”value”: “NOTIFICATION_BASED_PW_RECOVERY”}]}’ “https://localhost:9443/api/identity/user/v1.0/resend-code"

Here also you will get emails with the same confirmation code. (If you executed these within the configured time period ;-))

If you want to use the V1.0 APIs you can refer these APIs for password recovery.

In above all processes if you execute the following request for the initial request within the configured time period, the returning confirmation code of the recovery URL will be the same.

That’s all for today’s chapter guys. Let’s meet with another chapter. #StayHome and #StaySafe guys.

Adios Amigos….!!

References and Resources








Shan Chathusanda Jayathilaka

Senior Software Engineer @ WSO2 | Graduate in Computer Science, University of Ruhuna