This documentation is for WSO2 Identity Server 5.7.0 . View documentation for the latest release.

All docs This doc
Skip to end of metadata
Go to start of metadata

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 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.fromProvide the email address of the SMTP account.
    mail.smtp.userProvide the username of the SMTP account.
    mail.smtp.passwordProvide 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">[email protected]</property>
        <property key="mail.smtp.user">abcd</property>
        <property key="mail.smtp.password">xxxx</property>
        <property key=""></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>
  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="">
        <from streamName="id_gov_sms_notify_stream" version="1.0.0"/>
        <mapping customMapping="enable" type="json">
        <to eventAdapterType="http">
            <property name="http.client.method">httpPost</property>
            <property name="http.url">http://localhost:8006/productionStream</property>
  4. Configure the file found in the <IS_HOME>/repository/conf/identity folder to subscribe the event handler to trigger notifications.

    Sample notification handler configuration 
     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.

    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.


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

  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. 

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

       Click for more information on newly added properties
      ConfigurationDescriptionUnitDefault Value
      • The validity period of the resend code returned by the password recovery API.
      • Used in password recovery.
      Minutes1 minute
      • The validity period of the recovery code returned by password init API and username init API.
      Minutes1 minute
      • The validity period of the SMS OTP for password reset.
      • Used in password recovery.
      Minutes1 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:

    The claim URI is case sensitive. 

    NOTE: Not configuring the above claim will give errors.

  • No labels