Skip to content

Configuring Username Recovery

WSO2 Identity Server enables recovering user accounts where the user has forgotten the username. This is done by matching the user claims that are related to user attributes. The user will be prompted to enter values for these user attributes. If the value entered by the user matches with the claims, the corresponding username will be emailed to the user’s registered email ID.

User Name Recovery


Pickup is a cab company that has many employees who use different credentials to sign in to different internal enterprise applications. Larry who is a new recruit at Pickup has forgotten the username.

Let's learn how Larry can recover the password by providing the corresponding profile information!

Set up

Follow the steps below to configure WSO2 Identity Server to enable username recovery.

  1. Open the deployment.toml file in the <IS_HOME>/repository/conf directory.

    1. Check whether the following listener configs are in place.

      priority= "50"
      enable = false
      priority= "95"
      enable = true
    2. To configure the email server to send emails requesting password reset, add the following configurations.

      • from_address: This is the email address from which the confirmation email will be sent.
      • username: This is the username of the given email address.
      • password: This is the password of the given email address.
      from_address= ""
      username= ""
      password= ""
      hostname= ""
      port= 587
      enable_start_tls= true
      enable_authentication= true
      from_address= "[email protected]"
      username= "wso2iamtest"
      password= "Wso2@iam70"
      hostname= ""
      port= 587
      enable_start_tls= true
      enable_authentication= true

      If you are using a Google email account

      Google has restricted third-party applications and less secure applications from sending emails by default. As WSO2 Identity Server acts as a third-party application when sending emails for password entry, follow the steps below to enable your Google email account to provide access to third-party applications.

      1. Access

      2. Under Signing in to Google section, turn off the 2-step Verification option.

      3. Enable Less secure app access in the Google Account's Security section.

  2. Restart WSO2 Identity Server.

  3. On the Main menu of the Management Console, click Identity > Identity Providers > Resident.

    Resident menu-item

  4. Under the Account Management section, click Account Recovery.

    Account Recovery Option

  5. Select the following check boxes:

    • Username recovery
    • Manage notifications sending internally

    User Name Recover options


    The recommended Recovery callback URL regex to use when testing the product is ^https:\/\/localhost:9443\/.*. However, users should modify it to meet their requirements when they deploy the product.

  6. Click Update.

Try out

  1. To create the user account for Larry:

    1. On the Main menu of the Management Console, click Identity > Users and Roles > Add.

      Add Users and Roles menu-item

    2. Click Add New User.

      Add New User option

    3. Enter the required data as follows.

      Add New User screen

      • Domain: Primary
      • Username: Larry
    4. Click Finish.

  2. To assign login permissions to the user:

    1. Click the View Roles option of Larry.

      View Roles option

    2. Click Permissions.

      Role Permissions option

    3. Select Login and click Update.

      Login permission

  3. To add Larry's email Id:

    1. Click User Profile option of Larry.

      User Profile option

    2. Enter an email address to which Larry's password recovery emails will be sent. Enter the first name as Larry.

      User Email option

    3. Click Update.

  4. To mimic a forgotten username:

    1. On the Sign In screen of the WSO2 Identity Server My Account at https://localhost:9443/myaccount, click Username.

      Sign In form

    2. Enter the first name as Larry.

      Consent form

    3. Click Submit.

    4. An email with the username is sent to the given email address.

      Account Recovery email