Password Recovery Via User-Preferred Notification Channel¶

This section guides you through setting up password recovery for users to recover a lost or forgotten password.

Password recovery flow¶

The password recovery flow of WSO2 Identity Server is as follows:

1. User provides a set of unique claims to identify the user account.
2. The API prompts the user to select a channel from the available notification channels for receiving the username recovery notification.
3. The user selects a notification channel.
4. The server sends the recovery notification to the user via the preferred notification channel.
5. If the preferred channel is:
   • Email: The user can click the reset link sent to the registered email address and reset the password.
   • SMS: The user provides the received One-Time Password (OTP) and resets the password.

The following sections walk you through configuring and trying out password recovery via SMS and Email channels.

[event.default_listener.identity_mgt]
priority= "50"
enable = false
[event.default_listener.governance_identity_mgt]
priority= "95"
enable = true
[event.default_listener.governance_identity_store]
priority= "97"
enable = true

Set up password recovery¶

Follow the steps given below to recover a user in the super tenant (i.e., carbon.super).

1. Add the following properties to the deployment.toml file in the IS_HOME/repository/conf folder to configure WSO2 Identity Server to send confirmation emails.

   [output_adapter.email]
   from_address= "[email protected]"
   username= "wso2iamtest"
   password= "Wso2@iam70"
   hostname= "smtp.gmail.com"
   port= 587
   enable_start_tls= true
   enable_authentication= true

   Note

   • Add this configuration only if you wish to configure WSO2 Identity Server to send confirmation emails. See Configure the Email Sending Module for more information.
   • Alternatively, you can use your own email managing mechanism.

2. Add the following properties to the deployment.toml file.

   [identity_mgt.notification_channel_recovery]
   recovery_code_validity=2
   
   [identity_mgt.resend_notification]
   resend_code_validity=5
   
   [identity_mgt.password_reset_sms]
   sms_otp_validity=2

   Property Name	Description
   recovery_code_validity	Validity period of the recovery code given after initiating username/ password recovery. Unit : minutes Default value : 1 note If you have configured username recovery via the user-preferred notification channel, the above field is already configured.
   resend_code_validity	Validity period of the recovery code given after initiating password recovery. Unit : minutes Default value : 1
   sms_otp_validity	Validity period of SMS OTP when the selected channel is SMS. Unit : minutes Default value : 1

3. Add an event publisher to <IS_HOME/repository/deployment/server/eventpublishers.

   You can use the following sample publisher to call a REST service to send confirmation codes. This sample uses the http output adapter.

   Sample Event Publisher

   <?xml version="1.0" encoding="UTF-8"?>
   <eventPublisher name="HTTPOutputEventAdapter" processing="enable"
       statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventpublisher">
       <from streamName="id_gov_sms_notify_stream" version="1.0.0"/>
       <mapping customMapping="enable" type="json">
           <inline>{"api_key":"4c9374",
               "api_secret":"FtqyPE93",
               "from":"NEXMO",
               "to":{{ mobile }},
               "text":{{ body }}
               }</inline>
       </mapping>
       <to eventAdapterType="http">
           <property name="http.client.method">httpPost</property>
           <property name="http.url">https://rest.nexmo.com/sms/json</property>
       </to>
   </eventPublisher>

   This publisher uses NEXMO as the SMS REST service provider. For more information on writing a custom HTTP event publisher, see HTTP Event Publisher.

   Note

   If a WSO2 IS instance is already running, restart it to apply the above configurations.

4. On the Management Console, go to Identity Providers > Resident > Account Management, expand Account Recovery, and configure the following properties.

   

   Field	Description
   Notification based password recovery	Enable password recovery with notifications for the current tenant domain.
   Security question based password recovery	Enable security question-based password recovery.
   Manage notifications sending internally	Select to configure WSO2 Identity Server to send confirmation emails to the user. If the client application handles notification sending already, clear this checkbox.
   Notify when recovery success	Send a notification when password reset is successful.
   Recovery link expiry time in minutes	Validity period of the password reset email link. Unit : minutes Default : 1440
   SMS OTP expiry time	Validity period of the password reset OTP. Unit : minutes Default : 1

Manage notification templates¶

This section guides you on how to manage your email and SMS notification templates in WSO2 Identity Server.

Manage email notification templates¶

The email notification templates are stored in the IS_HOME>/repository/conf/email/email-admin-config.xml file, and they can be edited using the Management Console.

Manage SMS notification templates¶

The templates for SMS notifications are stored in the registry. Follow the steps below to edit the existing sms notification templates.

1. Log in to the Management Console and go to Main > Registry> Browse.

2. On the tree view tab, click system > config > identity > sms. This displays all the available SMS notification templates.

   

3. Select a template and click en_us to view the template.

4. Click Display as text to view the template or click Edit as text to edit the template.

   

Try it out¶

Create a user for recovery¶

1. Log in to the Management Console and click Main -> Identity -> Users and Roles -> Add.

2. Click Add New User and enter user credentials.

   Note

   For more details on creating users and roles, see Adding Users and Roles.

3. Go to Users and Roles > List > Users.

4. Find the user from the list and click View Roles.

5. Click Permissions to edit the default permissions.

6. From the list of permissions, select the Login permission and click Update.

   Warning

   This updates the permissions of the role. Therefore, all the users with the current role will receive login permissions.

7. Go to Users and Roles > List > Users, click User Profile, and update the email and mobile of the user.

With internal notification management¶

1. Use the following command to create a password recovery request.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/init" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"claims\":[{\"uri\":\"http://wso2.org/claims/givenname\",\"value\":\"user1\"}],\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   [
   {
   "mode": "recoverWithNotifications",
   "channelInfo": {
       "recoveryCode": "254d9446-faef-4763-be8a-f71e80c4715b",
       "channels": [
           {
               "id": "1",
               "type": "EMAIL",
               "value": "s********@g***l.com",
               "preferred": false
           },
           {
               "id": "2",
               "type": "SMS",
               "value": "*******3902",
               "preferred": true
           }
       ]
   },
   "links": [
       {
           "rel": "next", 
           "href": "/t/carbon.super/api/users/v1/recovery/password/recover",
           "type": "POST"
       }
   ]
   },
   {
   "mode": "recoverWithChallengeQuestions",
   "links": [
       {
       "rel": "next",
       "href": "/t/carbon.superidentity/recovery/v0.9/security-question?username=sominda2",
       "type": "GET"
       }
   ]
   }
   ]

   Note

   • The validity period of the recovery code is determined by the second step of configuring password recovery.
   • To try out password recovery with a challenge question, see Configuring Password Reset with Challenge Questions.

2. Use the recoveryCode and a preferred channel id to get notifications via that channel.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/recover" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"recoveryCode\":\"1234-5678-2455-3433\",\"channelId\":\"1\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
   "code": "PWR-02001",
   "message": "Password recovery information sent via user preferred notification channel.",
   "notificationChannel": "EMAIL",
   "resendCode": "8dde8fd4-c58d-4408-a835-a9954ebc278a",
   "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. If you want to resend notifications to the user via the notified channel in the above step, use the resendCode with the resend notifications API.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/resend" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"resendCode\":\"1234-2ws34-1234\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
   "code": "UAR-02001",
   "message": "Confirmation code resent to the user.",
   "notificationChannel": "EMAIL",
   "resendCode": "8ebefae5-0a80-4edf-ac2d-6034384e45c0",
   "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"
       }
   ]
   }

4. Use the confirmation code received by the user to verify the confirmation code.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/confirm" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"confirmationCode\":\"1234-2ws34-12345\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
       "resetCode": "90b9ce11-7642-4f50-aa06-386011b7de66",
       "links": [
           {
               "rel": "next",
               "href": "/t/carbon.super/api/users/v1/recovery/password/reset",
               "type": "POST"
           }
       ]
   }

5. Use the resetCode and the new password to update the existing password and recover the account.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/reset" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"resetCode\":\"aefaef12-951e-4a42-b01b-3118798f58c3\",\"password\":\"newPassword\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
       "code": "PWR-02005",
       "message": "Successful password reset."
   }

With external notification management¶

1. Use the following command to create a password recovery request.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/init" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"claims\":[{\"uri\":\"http://wso2.org/claims/givenname\",\"value\":\"user1\"}],\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   [{
   "mode": "recoverWithNotifications",
   "channelInfo": {
       "recoveryCode": "9ed0ed58-593a-48d8-90b3-ae745a6d7aae",
       "channels": [
           {
               "id": "1",
               "type": "EXTERNAL",
               "value": ""
           }
       ]
   },
   "links": [
       {
           "rel": "next",
           "href": "/t/carbon.super/api/users/v1/recovery/username/recover",
           "type": "POST"
       }
   ]
   }]

   Note

   The validity period of the recovery code is determined by the 2^nd step of configuring password recovery

2. Use the recoveryCode and a channel id to get the recovered username.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/recover" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"recoveryCode\":\"1234-5678-2455-3433\",\"channelId\":\"1\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
   "code": "PWR-02001",
   "message": "Password recovery information sent via user preferred notification channel.",
   "notificationChannel": "EXTERNAL",
   "confirmationCode": "90b9ce11-7642-4f50-aa06-386011b7de66",
   "resendCode": "b24bcfc0-3ee3-4a7d-964c-e3e6e3098c08",
   "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. If you want to resend the notifications, use the resendCode with the resend notifications API.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/resend" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"resendCode\":\"1234-2ws34-1234\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
   "code": "UAR-02001",
   "message": "Confirmation code resent to the user.",
   "notificationChannel": "EXTERNAL",
   "confirmationCode": "8ebcf3a1-b278-415c-b077-9b15fbf9bfdf",
   "resendCode": "b037478d-15e1-4f3d-ab7b-ad917dc73904",
   "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"
       }
   ]
   }

4. Use the confirmationCode to verify the password reset.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/confirm" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"confirmationCode\":\"1234-2ws34-12345\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
       "resetCode": "90b9ce11-7642-4f50-aa06-386011b7de66",
       "links": [
           {
               "rel": "next",
               "href": "/t/carbon.super/api/users/v1/recovery/password/reset",
               "type": "POST"
           }
       ]
   }

5. Use the resetCode and the new password to update the existing password and recover the account.

   Request Format

   curl -X POST "https://localhost:9443/api/users/v1/recovery/password/reset" -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "accept: application/json" -H "Content-Type: application/json" -d "{\"resetCode\":\"aefaef12-951e-4a42-b01b-3118798f58c3\",\"password\":\"newPassword\",\"properties\":[{\"key\":\"key\",\"value\":\"value\"}]}"

   ---

   Sample Request

   {
       "code": "PWR-02005",
       "message": "Successful password reset."
   }