Configuring Account Recovery Via User Preferred Notification Channel

WSO2 Identity Server allows the user to recover their account username or password via a user-preferred channel. After initiating a 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. 

This page guides you through configuring a user-preferred channel for account recovery and trying it out. 

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.

Configure WSO2 Identity Server

1. Configure the following email settings in the <IS_HOME>/repository/conf/output-event-adapters.xml file. 

   mail.smtp.from	Provide the email address of the SMTP account.
   mail.smtp.user	Provide the username of the SMTP account.
   mail.smtp.password	Provide the password of the SMTP account.

   <adapterConfig type="email">
       <!-- Comment mail.smtp.user and mail.smtp.password properties to support connecting SMTP servers which use trust
           based authentication rather username/password authentication -->
       <property key="mail.smtp.from">abcd@gmail.com</property>
       <property key="mail.smtp.user">abcd</property>
       <property key="mail.smtp.password">xxxx</property>
       <property key="mail.smtp.host">smtp.gmail.com</property>
       <property key="mail.smtp.port">587</property>
       <property key="mail.smtp.starttls.enable">true</property>
       <property key="mail.smtp.auth">true</property>
       <!-- Thread Pool Related Properties -->
       <property key="minThread">8</property>
       <property key="maxThread">100</property>
       <property key="keepAliveTimeInMillis">20000</property>
       <property key="jobQueueSize">10000</property>
   </adapterConfig>

2. Create a new stream and add it to the <IS_HOME>/repository/deployment/server/eventstreams folder. A sample stream is given below.

   Sample stream

   {
   	"name": "id_gov_sms_notify_stream",
   	"version": "1.0.0" 
   } 

3. Create a new publisher and add it to the <IS_HOME>/repository/deployment/server/eventpublishers folder.
   For more information, see HTTP Event Publisher in the WSO2 Data Analytics Server documentation. 

   Sample 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"="4cb4asxasx9374",
               "api_secret"="asacareftbr31244",
               "from"="NEXMO",
               "to"={{mobile}},
               "text"={{body}}
               }</inline>
       </mapping>
       <to eventAdapterType="http">
           <property name="http.client.method">httpPost</property>
           <property name="http.url">http://localhost:8006/productionStream</property>
       </to>
   </eventPublisher>

4. Configure the identity-event.properties file found in the <IS_HOME>/repository/conf/identity folder to subscribe the event handler to trigger notifications.

   Sample notification handler configuration

   module.name.13=default.notification.sender 
   default.notification.sender.subscription.1=TRIGGER_SMS_NOTIFICATION 
   default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.stream=id_gov_sms_notify_stream:1.0.0
   default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.claim.mobile=http://wso2.org/claims/mobile 

    Click here for more information on stream configurations

   Stream configurations

   In the sample notification handler configuration code given above, 'stream' is a keyword. You can define the stream id as shown below. The event is then subscribed to the channel that triggers the event.

   default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.stream=id_gov_sms_notify_stream:1.0.0

   You can also define the claim URI using the following configuration. The handler will try to read the defined claim from the current user store and send it as the given attribute name 'sample_claim" to the event stream. 'claim' is a keyword used to the set the claims and 'sample_claim' is the attribute name used as the key which holds the value of the claim.

   default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.claim.sample_claim=http://wso2.identity/sample/claim

   You can define a property and value and pass it to the event stream using the following configuration.

   default.notification.sender.subscription.TRIGGER_SMS_NOTIFICATION.testcustomattribute=testattributevalue

5. Add the following configurations to the identity.xml in <IS_HOME>/repository/conf/identity folder.

   1. Add the following configurations within the <Recovery> <Notification> tags. 

      <ExpiryTime>
      	<ResendCode>1</ResendCode>
      	<RecoveryCode>1</RecoveryCode>
      </ExpiryTime>

   2. Add the following configurations within the <Recovery> <Notification> <Password> tags. 

      <ExpiryTime>
      	<smsOtp>1</smsOtp>
      </ExpiryTime>

       Click for more information on newly added properties

      Configuration	Description	Unit	Default Value
      ResendCode	The validity period of the resend code returned by the password recovery API. Used in password recovery.	Minutes	1 minute
      RecoveryCode	The validity period of the recovery code returned by password init API and username init API.	Minutes	1 minute
      smsOtp	The validity period of the SMS OTP for password reset. Used in password recovery.	Minutes	1 minute

6. Restart the server to apply the configurations.

Configure account recovery

1. Click Resident under Identity Providers. 
2. Expand Account Management Policies and then expand Account Recovery.  
3. Select Enable Notification Based Password Recovery and Enable Username Recovery. 
   
4. Set the SMS OTP Expiry Time to configure the validation time of the OTP codes. 
5. Select Internal Notification Management to enable sending notifications from WSO2 Identity Server. WSO2 IS is capable of sending notifications via Email or SMS. 
6. Add the following SMS templates to the registry. For instructions, see Managing SMS Notification Templates Using the Registry. 
   • passwordReset
   • passwordResetSucess 
   • resendPasswordReset
   • accountIdRecovery
    Template Properties

   Username recovery template

   • Folder name: accountidrecovery
   • Resource name: en_us
   • Body = ["Hello, your username is {{userstore-domain}}/{{user-name}}@{{tenant-domain}}"] 
   • display : accountIdRecovery 
   • type : accountIdRecovery 
   • locale : en_US

   Password reset notification template

   • Folder name : passwordreset
   • Resource name: en_us
   • Body =  ["Your One-Time Password is : {{confirmation-code}}"] 
   • display : passwordReset 
   • type : passwordReset 
   • locale : en_US

   Password reset successful template

   • Folder name: passwordresetsucess
   • Resource name: en_us
   • Body = ["Successful Password Reset"] 
   • display : passwordResetSucess 
   • type : passwordResetSucess 
   • locale : en_US

   Resend password reset code template

   • Folder name: resendpasswordreset
   • Resource name: en_us
   • Body = ["Your One-Time Password is : {{confirmation-code}}"] 
   • display : resendPasswordReset 
   • type : resendPasswordReset 
   • locale : en_US

7. Click Claims > Add > Add Local Claim. 

8. Add the Preferred Channel Claim as a local claim: http://wso2.org/claims/identity/preferredChannel.

   The claim URI is case sensitive. 

   NOTE: Not configuring the above claim will give errors.