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

Configuring reCaptcha for Username Recovery

Owned by Gomathy Kumarakuruparan (Unlicensed)
Last updated: Mar 28, 2019
2 min read

The user account recovery feature implemented in the WSO2 Identity Server helps to recover the username of the account in case the user forgets it. This recovery process can also be secured with captcha verification.

By configuring reCaptcha, you can mitigate or block brute force attacks. 

For more information on setting up username recovery, see Username Recovery. 

For more information on brute force attacks, see Mitigating Brute Force Attacks.

There are two ways to configure this feature.

  1. Configuring username recovery with reCaptcha for a tenant.
  2. Configuring username recovery with reCaptcha globally.

Configuring username recovery with reCaptcha for a tenant

Follow the instructions given below to configure username recovery with reCaptcha for a specific tenant.

  1. Set up reCaptcha with WSO2 Identity Server. For instructions on how to do this, and for more information about reCaptcha, see Setting Up ReCaptcha.
  2. Enable the EnableMultiTenancy context-parameter in the accountreoceryendpoint web.xml file.
  3. Start WSO2 Identity Server and log into the management console as tenant admin.

  4. On the Main tab, click on Identity Provider → Resident Identity Provider.

  5. Expand the Account Management Policies tab, then click on Account Recovery. 

  6. Select the Enable reCaptcha for Username Recovery checkbox to enable reCaptcha for the username recovery flow.

  7. You have now successfully configured reCaptcha for the username recovery flow. Start the WSO2 Identity Server and log into the end user dashboard.

    If you have changed the port offset or modified the hostname, change the port or hostname accordingly.

  8. Click on Forgot Username.


Enter the domain name in the page that appears next. 


Clicking on Proceed to Username Recovery redirects you to the following page where you can select the recaptcha option for username recovery. 


Configuring username recovery with reCaptcha globally

Follow the instructions given below to configure username recovery with reCaptcha globally.

  1. Navigate to the identity.xml file in <IS_HOME>/repository/conf/identity and uncomment the following configuration block.

    To avoid any configuration issues, perform Step-1 before starting the WSO2 Identity Server product instance.

    <Recovery>
     <ReCaptcha>
                <Password>
                <Enable>false</Enable>
                 </Password>
                 <Username>
                <Enable>true</Enable>
                 </Username>
     </ReCaptcha>

     <Notification>
           ………………
           ……………….

</Recovery>

  2. Set up reCaptcha with WSO2 Identity Server. For instructions on how to do this and more information about reCaptcha, see Setting Up ReCaptcha.

  3. You have now successfully configured reCaptcha for the username recovery flow. Start WSO2 Identity Server and log into the end user dashboard.

    If you have changed the port offset or modified the hostname, change the port or hostname accordingly.

  4. Click the Forgot Username link.


Clicking on Forgot Username redirects you to the following page where you can select the recaptcha option for username recovery.