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

Extending Username and Password Recovery

Owned by Former user (Deleted)
Last updated: Jan 29, 2020
7 min read

To use this feature, apply the 5976 WUM update for WSO2 IS 5.7.0 using the WSO2 Update Manager (WUM).

To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide.

WSO2 Identity Server allows the user to recover their account username or password via a user-preferred channel. After initiating username or password recovery, the user will be prompted to select a recovery channel and the user will then be notified via the selected notification channel. 

Channel NameClaimChannel Verified Claim
SMShttp://wso2.org/claims/mobilehttp://wso2.org/claims/phoneVerified
EMAILhttp://wso2.org/claims/emailaddresshttp://wso2.org/claims/emailVerified

Account recovery flow

  • The user provides a set of unique claims to identify the user account.  
  • Then, the server will prompt the user to select one of the available notification channels to receive the recovery notification.
  • The user selects a notification channel.
  • The server sends the recovery notification to the user via the preferred notification channel.
  • If the flow is initiated for password recovery and the preferred channel is:
    • Email: Click on the reset link in the email and reset the password.
    • SMS: Provide the received One-Time Password(OTP) and reset the password.

This guide provides information regarding the APIs used for this implementation.

Before you begin

For instructions on configuring WSO2 IS to use a preferred notification channel, see Configuring Account Recovery Via User Preferred Notification Channel.

WSO2 Identity Server supports managing notifications for account recovery both internally and externally. 

  • Internal Notification Management: Notification sending is managed by WSO2 Identity Server.
  • External Notification Management: Notification sending is managed by an external notification management mechanism.  
    To configure external notification management, unselect the Enable Internal Notification Management property in Account Recovery configurations.      

Username recovery APIs

With internally managed notifications

  1. Initiate a username recovery request using the following command. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/username/init" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"claims\": [ { \"uri\": \"http://wso2.org/claims/givenname\", \"value\": \"alex\" },{ \"uri\": \"http://wso2.org/claims/emailaddress\", \"value\": \"alex@gmail.com\" } ], \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"

    The channelId shown in the response below represents the available notification channels. Select one of the channels and give the relevant channelId in the next request. 

    Response
    [
   {
      "mode": "recoverWithNotifications",
      "channelInfo": {
      "recoveryCode": "a47474dd-0d5c-4df4-8674-528e23da033c",
      "channels": [
                  {"id": "1", "type": "EMAIL","value": "a********@g***l.com","preferred": false},
      			  {"id": "2","type": "SMS","value": "*******3902","preferred": false}
]
      },
       "links": [
{
   "rel": "next",
   "href": "/t/carbon.super/api/users/v1/recovery/username/recover",
   "type": "POST"
}
      ]
   } 
]

  2. Use the following command with the recoveryCode and a channelId to get the recovered username. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/username/recover" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"recoveryCode\": \"1234-5678-2455-3433\", \"channelId\": \"1\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
"code":"UNR-02001",
"message":"Username recovery information sent via user preferred notification channel."
,"notificationChannel":"SMS"
}

With externally managed notifications

  1. Initiate a username recovery request using the following command. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/username/init" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"claims\": [ { \"uri\": \"http://wso2.org/claims/givenname\", \"value\": \"alex\" },{ \"uri\": \"http://wso2.org/claims/emailaddress\", \"value\": \"alex@gmail.com\" } ], \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    [
  {
  "mode": "recoverWithNotifications",
  "channelInfo": {             
      "recoveryCode": "c07a5ab6-4e17-4835-80d9-23514c9c9a59",
      "channels": [                 
          {
            "id": "1"
            "type": "EXTERNAL", 
            "value": "EXTERNAL", 
            "preferred": false
          }
       ]
  },
  "links": [
      {
        "rel": "next",
         href": "/t/carbon.super/api/users/v1/recovery/username/recover",
         "type": "POST"
      }
    ]
   }
]

  2. Use the following command with the recoveryCode and a channelId to get the recovered username.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/username/recover" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"recoveryCode\": \"1234-5678-2455-3433\", \"channelId\": \"1\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
"code":"UNR-02002",
"message":"Username recovery information sent externally.",
"notificationChannel":"EXTERNAL",
"username":"alex1@carbon.super"
}

Password recovery APIs

With internally managed notifications

  1. Initiate a password recovery request using the following command. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/init" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"claims\": [ { \"uri\": \"http://wso2.org/claims/givenname\", \"value\": \"alex\" },{ \"uri\": \"http://wso2.org/claims/emailaddress\", \"value\": \"alex@gmail.com\" } ], \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"

    The channelId shown in the response below represents the available notification channels. Select one of the channels and give the relevant channelId in the next request. 

    Response
    [
    {
        "mode": "recoverWithNotifications",
        "channelInfo": {
            "recoveryCode": "693d3509-276c-473c-ac47-df10bb1f5050",
            "channels": [
                       {"id": "1","type": "EMAIL","value": "a********@g***l.com","preferred": false},
                       {"id": "2","type": "SMS","value": "*******3902","preferred": false}
            ]         
        },
        "links": [
{
"rel": "next",
"href": "/t/carbon.super/api/users/v1/recovery/password/recover",
"type": "POST"
}
         ]
    },
    {
       "mode": "recoverWithChallengeQuestions",
       "channelInfo": null,
       "links": [
{
"rel": "next",
"href": "/t/carbon.superidentity/recovery/v0.9/security-question?username=alex1",
"type": "GET"
}
       ]
   }
]

  2. Use the following command with the recoveryCode and a channelId to get the recovered username.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/recover" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"recoveryCode\": \"1234-5678-2455-3433\", \"channelId\": \"1\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}”
    Response
    {
    "code": "PWR-02001",
    "message": "Password recovery information sent via user preferred notification channel.",
    "notificationChannel": "SMS",
    "resendCode": "99fed343-a36a-46bb-8c66-6195f1d46734",
    "links": [
{
    "rel": "next",
    "href": "/t/carbon.super/api/users/v1/recovery/password/confirm",
    "type": "POST"
},
{
    "rel": "resend",
    "href": "/t/carbon.super/api/users/v1/recovery/password/resend",
    "type": "POST"
}
    ]
}

  3. Use the confirmation code recieved via the notification channel to confirm the validity of the confirmation code.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/confirm" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"confirmationCode\": \"1234-2ws34-12345\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
   "resetCode":"PGZKXO",
   "Links":[
{
   "Rel":"next",
   "href":"/t/carbon.super/api/users/v1/recovery/password/reset",
   "type":"POST"}
   ]
}

  4. Use the resetCode and give a new password to reset the password. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/reset" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"resetCode\": \"PGZKXO\", \"password\": \"string\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
   "code":"PWR-02005",
   "message":"Successful password reset."
}

  5. Use the resendCode recieved in step 2 to get a new confirmation code.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/resend" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"resendCode\": \"99fed343-a36a-46bb-8c66-6195f1d46734\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
   "code": "PWR-02002",
   "message": "successful_request",
   "notificationChannel": "EMAIL",
   "resendCode": "1234-12345-234-123456",
   "links": [
{
   "rel": "next",
   "href": "/api/users/v1/recovery/password/confirm",
   "type": "POST"
},
{
   "rel": "resend",
   "href": "/api/users/v1/recovery/password/resend",
   "type": "POST"
}
   ]
}

With externally managed notifications

  1. Initiate a password recovery request using the following command. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/init" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"claims\": [ { \"uri\": \"http://wso2.org/claims/givenname\", \"value\": \"alex\" },{ \"uri\": \"http://wso2.org/claims/emailaddress\", \"value\": \"alex@gmail.com\" } ], \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    [
    {
        "mode": "recoverWithNotifications",
        "channelInfo": {
            "recoveryCode": "693d3509-276c-473c-ac47-df10bb1f5050",
            "channels": [
                        {"id": "1","type": "EXTERNAL","value": "EXTERNAL","preferred": false}
            ]         
        },
        "links": [
{
"rel": "next",
"href": "/t/carbon.super/api/users/v1/recovery/password/recover",
"type": "POST"
}
         ]
    },
    {
       "mode": "recoverWithChallengeQuestions",
       "channelInfo": null,
       "links": [
{
"rel": "next",
"href": "/t/carbon.super/identity/recovery/v0.9/security-question?username=alex1",
"type": "GET"
}
       ]
   }
]

  2. Use the following command with the recoveryCode and a channelId to get the recovered username.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/recover" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"recoveryCode\": \"1234-5678-2455-3433\", \"channelId\": \"1\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}”
    Response
    {
   "code": "PWR-02001",
   "message": "Password recovery information sent via user preferred notification channel.",
   "notificationChannel":"EXTERNAL",
   "confirmationCode":"1ca49e58-61c2-43e5-a167-4f7331510e29",
   "resendCode": "d3dbf976-8dd7-49dc-ad7d-8d31248327e0",
   "Links":[
{
"rel": "next",
"href": "/t/carbon.super/api/users/v1/recovery/password/confirm",
"type": "POST"
}
   ]
}

  3. Use the confirmation code recieved via the notification channel to confirm the validity of the confirmation code.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/confirm" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"confirmationCode\": \"1234-2ws34-12345\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
   "resetCode":"PGZKXO",
   "Links":[
{
   "Rel":"next",
   "href":"/t/carbon.super/api/users/v1/recovery/password/reset",
   "type":"POST"}
   ]
}

  4. Use the resetCode and give a new password to reset the password. 

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/reset" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"resetCode\": \"1234567\", \"password\": \"password\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}
    Response
    {
   "code":"PWR-02005",
   "message":"Successful password reset."
}

  5. Use the resendCode recieved in step 2 to get a new confirmation code.

    Request
    curl -X POST "https://localhost:9443/api/users/v1/recovery/password/resend" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"resendCode\": \"1234-2ws34-1234\", \"properties\": [ { \"key\": \"key\", \"value\": \"value\" } ]}"
    Response
    {
   "code": "PWR-02002",
   "message": "successful_request",
   "notificationChannel": "EXTERNAL",
   "confirmationCode": "1234-12345-234-123456",
   "resendCode": "1234-12345-234-123456",
   "links": [
{
   "rel": "next",
   "href": "/api/users/v1/recovery/password/confirm",
   "type": "POST"
},
{
   "rel": "resend",
   "href": "/api/users/v1/recovery/password/resend",
   "type": "POST"
}
   ]
}