This documentation is for WSO2 Identity Server 5.0.0. View documentation for the latest release.
Page Comparison - Recovery with Notification (v.2 vs v.15) - Identity Server 5.0.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

WSO2 Identity Server supports Emailpassword recovery by using email-based notifications currently. The following describes the configuration needed the configurations required in order to send email using axis transport with Identity Server with regard to password recovery.

Here in after {carbon_home} refers to your Identity Server installation directory.

the axis2 mail transport in the WSO2 Identity Server for password recovery.

To recover with notification:

  1. Edit the <IS_HOME>/repository/conf/security/identity­-mgt.properties file with the following configuration under {carbon_home}/repository/conf/securityconfigurations.

    Code Block
    languagejava
    Identity.Listener.Enable=true
    Notification.Sending.Enable=true
    Notification.Expire.Time=3
    # expire the recovery after 3 minutes.
    Notification.Sending.Internally.Managed=true
    UserAccount.Recovery.Enable=true
    Captcha.Verification.Internally.Managed=false

    See the following table for descriptions of these configurations.

    ConfigurationDescription
    Identity.Listener.Enable=true
    This enables the identity listener.
    Notification.Sending.Enable=true

    This enables the email sending function when recovering the account and verifying the user creation.

    Notification.Expire.Time=3
    The time specified here is in minutes. In this case, the recovery expires after three minutes.
    Notification.Sending.Internally.Managed=true

    This enables the internal email sending module. If false, the email sending data is available to the application via a Web service. Thus the application can send the email using its own email sender.

    UserAccount.Recovery.Enable=true
    This enables the user account recovery process.
    Captcha.Verification.Internally.Managed=false
    # set this to true if you do not have existing captcha validation moduleEdit
    Set this to true if you do not have an existing captcha validation module.
  2. Ensure that the email-­admin-­config.xml file

    with

    has the following

    configuration under {carbon_home}

    configurations. This file is found in the <IS_HOME>/repository/conf/email directory.

    Define a  Use the email format with the type “passwordReset”. The following is a sample format:

    Code Block
    languagehtml/xml
    <configuration type="passwordReset">
    	<targetEpr>https://localhost:9443/carbon/admin­mgt/validator_ajaxprocessor.jsp</<targetEpr></targetEpr>
    	<subject>Password Reset Notification</subject>
    	<body>
    		Hi {first-­name}
    		We received a request to change the password on the {user-­name} account
    		associated with this e­mail address. If you made this request, please click
    		the link below to securely change your password:
    
    
    		{password-­reset-­linkhttp://localhost:9443/InfoRecoverySample/infoRecover/verify?confirmation={confirmation-code}&username={user-name}
    
    
    		If clicking the link doesn't seem to work, you can copy and paste the link
    		into your browser's address window.
    
    
    		If you did not request to have your {user-­name} password reset, simply
    		disregard this email and no changes to your
    		account will be made.
    	</body>
    	<footer>
    		Best Regards,
    		WSO2 Carbon Team http://www.wso2.com
    	</footer>
    	<redirectPath></redirectPath>
    </configuration>

    The email sent to user includes the {

    password

    confirmation-

    ­reset-­link} replaced with the URL defined within the targetEprtag appending the confirmation={key}

    code}, which the Identity Server API caller needs to pass along with the user name.

  3. Edit the axis.xml file with the following configuration under {carbon_home}. This file is found in the <IS_HOME>/repository/conf/axis2/ directory. Uncomment the following in the file and provide the necessary email settings.

    Code Block
    languagehtml/xml
    <transportSender name="mailto"
    class="org.apache.axis2.transport.mail.MailTransportSender">
    	<parameter name="mail.smtp.from">sampleemail@gmail.com</parameter>
    	<parameter name="mail.smtp.user">sampleemail@gmail.com<>sampleemail</parameter>
    	<parameter name="mail.smtp.password">password</parameter>
    	<parameter name="mail.smtp.host">smtp.gmail.com</parameter>
    	<parameter name="mail.smtp.port">587</parameter>
    	<parameter name="mail.smtp.starttls.enable">true</parameter>
    	<parameter name="mail.smtp.auth">true</parameter>
    </transportSender>

Recovering the password with email notification can be achieved using the exposed UserInformationRecoveryService where the WSDL . The WSDL file for this service can be found in the following URL of your Identity Server installation: https://localhost:9443/services/UserInformationRecoveryService?wsdl.

The service security is implemented using Captcha and confirmation codes expire after a while. Also for each communication, the generated confirmation code is not reused by the service. This makes the services secure and fails repeated attempts to access the same service. Hence, the sequence of calls which that the Calling Application calling application must do is as follows for email-based recovery:

  1. getCaptcha() -­ Generates a captcha.
  2. verifyUser() -­ Validates the captcha answer and username and returns a new key.
  3. sendRecoveryNotification() -­ Send an email notification with a confirmation code to the user. Need to provide the key from previous call.
  4. getCaptcha() ­- Generates a captcha when the user clicks on the URL.
  5. verifyConfirmationCode() -­ Validates the captcha answer and confirmation code. This returns a key.
  6. updatePassword() -­ Updates the password in the system. Need to provide the key from previous call, new password and returns the status of the update, true or false.

The flow of password recovery by email notification is as follows using the WSDL file (https://localhost:9443/services/UserInformationRecoveryService?wsdl):

  • First you need to get the captcha using the getCaptcha() method. 
  • The captcha details returned should be passed along with the visible captcha answer and user name to verifyUser() which is for user verification. 
  • Upon successful verification, it will return a code. Next, you need to call the sendRecoveryNotification() method to send the notification along with the code to the user. 
  • The generated email with the password reset link will be emailed to the user. 
  • Once the user clicks the reset link, the user should be directed to another captcha page for verification by calling getCaptcha()
  • The confirmation code must be verified along with the captcha answer by calling verifyConfirmationCode()
  • This will generate another code that must be passed to the updatePassword() method to update the password.
     
Tip

Tip: You can see this scenario in action using this sample. Follow the “I forgot my password” link to see the demo.