Wednesday, September 14, 2016

SMS OTP Two Factor Authentication through Identity Server

In this post, I will explain how to use SMS OTP multifactor authenticator through WSO2 Identity server. In this demonstration, I am using Twilio SMS Provider which was used to send the OTP code via SMS at the time authentication happens.

SMS OTP Authentication Flow

The SMS OTP authenticator of WSO2 Identity Server allows to authenticate the system using multifactor authentication. This authenticator authenticates with user name and password as a first step, then sending the one time password to the mobile via SMS as a second step. WSO2 IS will validate the code and let the user sign in accordingly

Add the authenticator configuration <IS_HOME>/repository/conf/identity/application-authentication.xml file under the <AuthenticatorConfigs> section.

<AuthenticatorConfig name="SMSOTP" enabled="true">
    <Parameter name="SMSOTPAuthenticationEndpointURL">https://localhost:9443/smsotpauthenticationendpoint/smsotp.jsp</Parameter>
    <Parameter name="SMSOTPAuthenticationEndpointErrorPage">https://localhost:9443/smsotpauthenticationendpoint/smsotpError.jsp</Parameter>
    <Parameter name="MobileNumberRegPage">https://localhost:9443/smsotpauthenticationendpoint/mobile.jsp</Parameter>
    <Parameter name="RetryEnable">true</Parameter>
    <Parameter name="ResendEnable">true</Parameter>
    <Parameter name="BackupCode">true</Parameter>
    <Parameter name="SMSOTPEnableByUserClaim">false</Parameter>
    <Parameter name="SMSOTPMandatory">false</Parameter>
    <Parameter name="usecase">association</Parameter>
    <Parameter name="secondaryUserstore">primary</Parameter>
    <Parameter name="CaptureAndUpdateMobileNumber">true</Parameter>
    <Parameter name="SendOTPDirectlyToMobile">false</Parameter>

Configure the Service Provider and Identity Provider Configuration as we normally configure for Two factor authentication. Now we will configure SMS OTP Identity provider for Twilio specific SMS Provider.

Go to ​­twilio​  and create a twilio account.

While registering the account, verify your mobile number and click on console home​  to get free credits (Account SID and Auth Token).

Twilio uses a POST method with headers and the text message and phone number are sent asthe payload. So the fields would be as follows.

SMS URL   ­04­01/Accounts/{AccountSID}/SMS/Messages.json
HTTP Method     POST
HTTP Headers    Authorization: Basic base64{AccountSID:AuthToken}
HTTP Payload    Body=$ctx.msg&To=$ctx.num&From={FROM_NUM}

You can go to SMS OTP Identity Provider and configure to send the SMS using Twilio SMS Provider.

Twilio SMS Provider Config

When authentication is happening in second step, the code will be sent to mobile no which is saved in mobile claim of  user's user profile.
If the user apply the code, WSO2 IS will validate the code and let the user sign in accordingly.


  1. Hi Could you please expain the step where you are configuring SMS OTP? I am using WSO2 IS 5.0.2. with resident identity provider and I can not see any place "SMSOTP Configuration."


    1. You need to create a identity provider for SMS OTP authenticator then add first step basic or any federated authenticator and second step SMS OTP authenticator in Service Provider. You can use wso2 store [1] and the documentation [2] to setup SMS OTP authenticator.
      [1] -
      [2] -


    2. Were you able to setup SMS OTP authenticator with WSO2 Identity Server?

  2. Hi Rajendram Kathees,

    I am using wso2is 5.4.0 and want to sent the smsotp which must get invalid after certain time and user cannot be able to send the smsotp more than 3 times. Does wso2 is support such fearures.


How to remove duplicate using overriding equals and hashCode methods in Java

import java.util.ArrayList; import java.util.HashSet; import java.util.Iterator; import java.util.List; import java.util.Set; public ...