Re-issue Existing Password Recovery Confirmation Code in Followed Recovery or Resend Requests

This article discusses a new feature which will be released for public distribution of WSO2 Identity Server 5.12.0. This feature was developed to overcome the following scenario:

1. The user requests a password recovery.
2. WSO2 Identity Server publishes an email that 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. The user waits a few minutes to receive the email. If the email is not received, the user will once again trigger a recovery flow of a recovery resend flow.
5. Now WSO2 Identity Server 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 due to the delay.
7. Meanwhile, the email which was published in step 2 can be received by the user.
8. The user will try to recover the password from that link, but the user is unable to recover it since the confirmation code in that email was already revoked/expired because of the second request.
9. This can happen again and again based on the delay of the email client.

You can refer to the following diagram for a deeper understanding of the above flow.

This scenario can be experienced by anyone. As such, we introduced a new way to handle this scenario (as shown below) for the notification-based password recovery flow.

1. WSO2 Identity Server receives a password recovery request.
2. It then checks whether the corresponding user already has a confirmation code.
3. If so, it checks whether the time duration between this request and the previous request is within the preconfigured time period (we added a configuration to keep a time period that can be configured).
4. If that is also true, WSO2 Identity Server sends the same confirmation code in the email to the corresponding user, without revoking it.

In this scenario, the 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 update of WSO2 Identity Server 5.10.0 and will be available in the public distribution from WSO2 Identity Server version 5.12.0.

The next section of this article, will discuss the configurations.

First, you need WSO2 Identity Server’s latest pack. Though the public distribution is not yet released, you can download the latest milestone release. I am using the 5.12.0-m18 version in this chapter. You would need to open the deployment.toml file located in <IS_HOME>/repository/conf directory and add the following configurations:

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

Next, you would need to add the email client configurations as described here and start the server. After starting the server, log in to the Management Console by using your username and password as admin. Go to the ‘Resident IDP’ in the Identity Providers section -> Account Management -> Account Recovery and enable ‘notification-based password recovery’.

Next, you would need to create a user and fill in the required fields for that user.

Now that you have successfully completed the configurations, we can test this feature. You have two ways to check this feature. The first 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 the email is successfully sent, the following message will appear to the user.

• Log in with the user’s email address and check the confirmation code in the password recovery link of the email with the subject Password Reset.
• Repeat 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 links for password recovery.

The confirmation code in the recovery URL will be similar to the below.



Another way to test this 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 use the API 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, you will also 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 to these APIs for password recovery.

To conclude this article; in all the above 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.

If this sounds interesting, we encourage you to try out the early adopter version of Asgardeo, an identity as a service (IDaaS) solution that enables developers without security expertise to easily embed customer identity and access management (CIAM) features into their apps within minutes.


You can also follow us on Twitter or join the IAM4Devs community. Alternatively, if you’re looking for an enterprise-grade, API-driven, open source solution that can manage millions of user identities without spiraling costs, please check out WSO2 Identity Server.