Thursday, October 15, 2015

A Step by Step Guide to Setup One Time Password Feature in WSO2 Identity Server 5.1.0

With ‘One Time Password’ [1] feature A.K.A OTP, WSO2 Identity Server facilitates users to have a new password every time they login. In this feature, when a user is authenticated to Identity Server, the current password of the account is automatically reset and the new password is emailed to the email address associated with the user account. With this feature, users do not need to remember their passwords. They can refer to the email received from Identity Server and get to know the password to be entered at the time of login.

This blog post provides a step by step guide for configuring the OTP feature using the Identity Server 5.1.0 version. If you are using Identity Server 5.0.0, refer [1] as the configuration file paths and properties can be bit different.

First we need to enable Identity Management Event Listener (IdentityMgtEventListener). For that, in IS_5.1.0_HOME/repository/conf/identity/identity.xml file, locate the org.wso2.carbon.identity.mgt.IdentityMgtEventListener and set enable attribute to true.

<EventListener type="org.wso2.carbon.user.core.listener.UserOperationEventListener" name="org.wso2.carbon.identity.mgt.IdentityMgtEventListener" orderId="50" enable="true"/>

Then we need to set the following properties related to this feature in IS_5.1.0_HOME/repository/conf/identity/ file.


In order to send email from Identity Server, we need to define the mail transport configurations. For that, we need to set the transportSender details in IS_5.1.0_HOME/repository/conf/axis2/axis2.xml file as following. Here I am adding an existing gmail email address. You can set the configuration according to your email server settings.

    <transportSender name="mailto"
       <parameter name="mail.smtp.from">[email protected]</parameter>
       <parameter name="mail.smtp.user">[email protected]</parameter>
       <parameter name="mail.smtp.password">mypassword</parameter>
       <parameter name=""></parameter>
       <parameter name="mail.smtp.port">587</parameter>
       <parameter name="mail.smtp.starttls.enable">true</parameter>
       <parameter name="mail.smtp.auth">true</parameter>

Then start/restart the Identity Server.

Next step is to add the claim configuration for One Time Password feature. You can view the existing claims of WSO2 claim dialect ( by going to Main -> Claims -> List -> in Management Console.

For adding the OTP claim, go to Main -> Claims -> Add.

Click on Add New Claim.

The claim we need to add is as following.

Claim Dialect
Claim URI
Mapped Attribute
Supported by Default

For the mapped attribute, you can specify any attribute name that is supported by the underlying userstore where you have users in. Here I am making this claim as ‘Supported by Default’ so that this claim will appear when we view the profile of users and we can set the value for the attribute from the user profile.

Once you add the claim, it appears as below when you view it.

Next step is to configure the Email Template for OTP where the end users will receive email from Identity Server according to this email template. Go to Configure -> Email Templates -> One Time Password.
You can change the template according to your requirements. The {otp-password} placeholder will be replaced by the user’s new password when the email is sent. Save the template after modifications.

Now let’s create a new user. Go to Main -> Identity -> Users and Roles -> Add.

Click on Add New User.

Type the username and password and click Next.
Here I’m assigning the admin role for the user for demonstration purpose. You can add a role that has login permission to test this feature.

Once the account is created, view the users and click on User Profile link for the created user.

Now we see the newly added claim attribute. When you view the profile of the user for the first time without updating the profile, the OTP attribute appears as a text box. You can provide true or false as the value in the textbox. If not you can just enter the values for required fields and Update the profile.

Upon updating the profile, if you had not given any value for OTP claim, by default false will be stored as the value. Next time you view the profile, the OTP attribute will appear as a checkbox as it now contains a boolean value (true or false). The logic in the UI to display a checkbox instead of a textbox is whether it contains true or false.

For enabling OTP for this user account, you can select the OTP claim checkbox and Update the profile.
Now you can test this by logging into the Management Console of Identity Server with the newly created user’s credentials.

Here we can successfully login with the account.

Once you login, you can check the inbox of the email address given for the user account. You can see that an email is received with the new password.

Upon next authentication, you have to use the password received in the email since the password of the account is reset to the one you received in the email.

Every time you authenticate to Identity Server with this account, your current password will be reset and the new password will be sent via email.

When you have enabled OTP feature, the password will be reset only for the user accounts where the OTP claim’s attribute value is set to true. For the user accounts where OTP claim value is set to false, the same password can be used continuously.


Tharindu Edirisinghe
Identity Server Team

No comments:

Post a Comment