Skip to content

Configuring SMS OTP

The SMSOTP authenticator allows you to authenticate user via SMS through WSO2 IS.

This topic provides instructions on how to configure the SMS OTP connector and the WSO2 Identity Server (WSO2 IS) to integrate using a sample app. This is configured so that SMSOTP is a second authentication factor for the sample application. See the following sections for more information.

Enable SMSOTP

Add the following configurations to <IS_HOME>/repository/conf/deployment.toml file to enable SMSOTP for WSO2 Identity Server.

[authentication.authenticator.sms_otp] 
name ="SMSOTP"
enable=true

[authentication.authenticator.sms_otp.parameters]
SMSOTPAuthenticationEndpointURL= "smsotpauthenticationendpoint/smsotp.jsp"
SMSOTPAuthenticationEndpointErrorPage= "smsotpauthenticationendpoint/smsotpError.jsp"
MobileNumberRegPage = "smsotpauthenticationendpoint/mobile.jsp"
RetryEnable = true
ResendEnable = true
BackupCode = true
SMSOTPEnableByUserClaim = true
SMSOTPMandatory = false
CaptureAndUpdateMobileNumber = true
SendOTPDirectlyToMobile = false
redirectToMultiOptionPageOnFailure = false
Value Description
name Define the authenticator as SMSOTP.
enable Enable or diable the authenticator.
SMSOTPAuthenticationEndpointURL Authentication endpoint URL of the authenticator.
SMSOTPAuthenticationEndpointErrorPage Error page that will be displayed in an authentication failure.
MobileNumberRegPage Range of usable mobile numbers to send SMSs.
RetryEnable Define whether to retry or not.
ResendEnable Define whether to enable resending the SMMSOTP or not in case a user enters an incorrect code.
BackupCode Define whether to use a backup code instead of the actual SMS code or not.
SMSOTPMandatory If the value is true, the second step will be enabled by the admin. The user cannot be authenticated without SMS OTP authentication. This parameter is used for both super tenant and tenant in the configuration. The value can be true or false.
SMSOTPEnableByUserClaim Disabl the 'SMS OTP disabling by user' functionality. The value can be either true or false. If the value is set to true, the user can enable and disable the SMS OTP according to what the admin selects in SMSOTPMandatory parameter value.
CaptureAndUpdateMobileNumber When SMSOTPMandatory is set to true and the user forgets to update the mobile number in a specific user profile where this property is set to true, the user can update a mobile claim with value during the authentication time and use that mobile number to send OTP. This update functionality will happen in the first login only. For the next logins, the updated mobile number will be used.
SendOTPDirectlyToMobile When SMSOTPMandatory is set to true and the user does not exist in the user store and if the admin sets SendOTPDirectlyToMobile to true , the user can enter the mobile number in authentication time in a mobile number request page; the OTP will be directly sent to that mobile number.
redirectToMultiOptionPageOnFailure During a failed attempt unable redirect to the Multi Option Page where the user can select the authentication mechanism.

Note

The SMS provider is the entity that is used to send the SMS. The SMSOTP connector has been configured such that it can be used with most types of SMS APIs. Some use the GET method with the client secret and API Key encoded in the URL (e.g., Nexmo), while some may use the POST method when sending the values in the headers and the message and telephone number in the payload (e.g., Clickatell). This could change significantly between different SMS providers. The configuration of the connector in the identity provider would also change based on this.

Deploying travelocity sample application

Follow this guide to deploy and configure the travelocity.com sample app in order to try this scenario.

Once this is done, the next step is to configure the WSO2 Identity Server by adding an identity provider and a service provider.

Configuring the identity provider

Now you have to configure WSO2 Identity Server by adding a new identity provider.

  1. Start the Server.

  2. Download the certificate of the SMS provider by going to the SMS providers website on your browser, and clicking the HTTPS trust icon on the address bar.

    Example

    If you wish to have NEXMO as your SMS provider, navigate to https://www.nexmo.com, and click the padlock next to the URL on Chrome and download the certificate.

  3. Navigate to the <IS_HOME>/repository/resources/security directory via the terminal and i mport the downloaded certificate into the WSO2 IS client keystore.

    keytool -importcert -file <CERTIFICATE_FILE_PATH> -keystore client-truststore.jks -alias "Nexmo" 
  4. You are prompted to enter the keystore password. The default client-truststore.jks password is wso2carbon.

  5. Log into the management console as an administrator.

  6. Navigate to Main tab -> Identity -> Identity Providers -> Add.

  7. Give a suitable name (e.g., SMSOTP) as the Identity Provider Name.

  8. Go to the SMS OTP Configuration under Federated Authenticators.

  9. Select both check-boxes to Enable SMSOTP Authenticator and to make it the Default.

  10. Enter the SMS URL, the HTTP Method used (e.g., GET or POST), and the headers and payload if the API uses any.

    Info

    • If the text message and the phone number are passed as parameters in any field, include them as $ctx.num and $ctx.msg respectively.

    • Optionally, enter the HTTP response code the SMS service provider sends when the API is successfully called. Nexmo API and  Bulksms API sends 200 as the code, while Clickatell and Plivo send 202. If this value is unknown, leave it blank and the connector checks if the response is 200, 201 or 202.

    Click here to configure Nexmo as the service provider.

    Follow the steps given below if Nexmo is used as the SMS provider:

    1. Go to https://dashboard.nexmo.com/sign-up and sign up.
    2. Once you successfully register, the API key and secret are displayed. Copy and save them as you need them for the next step.
      Example:
      nexmo-config
    3. The Nexmo API requires the parameters to be encoded in the URL, so the SMS URL would be as follows.
      SMS URL https://rest.nexmo.com/sms/json?api_key=&api_secret=&from=NEXMO&to=ctx.num&text=ctx.msg
      HTTP Method POST
    Click here to configure Clickatell as the service provider.

    Follow the steps given below if Clickatell is used as the SMS provider:

    1. Go to https://secure.clickatell.com/#/login and create an account.
    2. The Auth token is provided when you register with Clickatell.

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

      SMS URL https://api.clickatell.com/rest/message
      HTTP Method POST
      HTTP Headers X-Version: 1,Authorization: bearer ,Accept: application/json,Content-Type: application/json
      HTTP Payload {"text":" $ctx.msg ","to":[" $ctx.num "]}

    Click here to configure Plivo as the service provider.

    Follow the steps given below if Plivo is used as the SMS provider:

    1. Sign up for a free Plivo trial account .
    2. Phone numbers must be verified at the Sandbox Numbers page (add at least two numbers and verify them).

    3. The Plivo API is authenticated with Basic Auth using your AUTH ID and AUTH TOKEN , Your Plivo AUTH ID and AUTH TOKEN can be found when you log in to your dashboard.

    4. Plivo uses a POST method with headers, and the text message and phone number are sent as the payload. So the fields would be as follows.
      SMS URL https://api.plivo.com/v1/Account/{auth_id}/Message/
      HTTP Method POST
      HTTP Headers Authorization: Basic ********,Content-Type: application/json
      HTTP Payload {"src":"+94*********","dst":"ctx.num","text":"ctx.msg"}
    Click here to configure Bulksms as the service provider.

    Follow the steps given below if Bulksms is used as the SMS provider:

    1. Go to https://www2.bulksms.com/login.mc and create an account.
    2. While registering the account, verify your mobile number and click Claim to get free credit.
      mobile-number-claim
    Bulksms API authentication is performed by providing the
    username and password request parameters.
    1. Bulksms uses the POST method and the required parameters are to be encoded in the URL. So the fields would be as follows.
      SMS URL https://bulksms.vsms.net/eapi/submission/send_sms/2/2.0?username=&password=&message=ctx.msg&msisdn=ctx.num
      HTTP Method POST
      HTTP Headers Content-Type: application/x-www-form-urlencoded
    Click here to configure Twilio as the service provider.

    You will need a Twilio-enabled phone number (a phone number purchased through Twilio) to send SMS using Twilio.

    Follow the steps given below if Twilio is used as the SMS provider:

    1. Go to https://www.twilio.com/try-twilio and create an account.
    2. While registering the account, verify your mobile number and click on console home https://www.twilio.com/console to get free credit (Account SID and Auth Token).

    3. Twilio uses the POST method with headers, and the text message and phone number are sent as the payload. The fields would be as follows.

      SMS URL https://api.twilio.com/2010-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=urlencode{FROM_NUM}

    4. After signing up for your trial account, navigate to the Phone Numbers page in your console. You’ll see the phone number that has been selected for you. Note the phone number’s capabilities, such as "Voice", "SMS", and "MMS". twilio-phone-number twilio-phone-number-2

    Get your first Twilio phone number and use that as the FROM_NUM in your HTTP Payload. For more information, see this tutorial in the Twilio documentation.

  11. Click Register .

Configuring the service provider

The next step is to configure the service provider.

  1. In the Deploying travelocity sample application section you have configured a service provider in WSO2 Identity server. Now edit the service provider to configure SMS OTP.

  2. Go to Claim configuration and select the http://wso2.org/claims/mobile claim for the Subject Claim URI.

    subject-claim-uri

  3. Go to Local and Outbound Authentication Configuration section.

    1. Select the Advanced configuration radio button option.

    2. Creating the first authentication step:

      1. Click Add Authentication Step.

      2. Click Add Authenticator that is under Local Authenticators of Step 1 to add the basic authentication as the first step.
        Adding basic authentication as a first step ensures that the first step of authentication will be done using the user's credentials that are configured with the WSO2 Identity Server

    3. Creating the second authentication step:

      1. Click Add Authentication Step.

      2. Click Add Authenticator that is under Federated Authenticators of Step 2 to add the SMSOTP identity provider you created as the second step.
        SMSOTP is a second step that adds another layer of authentication and security.

      creating-the-second-authentication

  4. Click Update to save the changes.

You have now added and configured the service provider.

Updating the mobile number of the user

Follow the steps given below to update the mobile number of the users in WSO2 IS.

  1. Navigate to Main -> Identity -> Users and Roles -> List -> Users to view existing users.

  2. Click User Profile of the user you want to edit and update the mobile number.

    Warning

    The mobile number needs to be in the following format.

    Example: 94778888888

    NOTE: If the format is wrong you would not get the text message.

    Note

    Make sure the number is registered with an SMS provider in order to send the SMS. For this tutorial, you can use the mobile number that was used to register with the SMS provider.

Add Disable SMSOTP option for Users

  1. Navigate to Main -> Identity -> Claims -> List -> Click http://wso2.org/claims.

  2. Find Claim Disable SMSOTP and click Edit.

  3. Enable Supported by Default option and click Update.

Now Disable SMSOTP option is available for the user.

Note

To verify whether the option is available for the users, navigate to a user profile of a user and check Disable SMSOTP option is available.

add-disable-smsotp-option

Configuring backup codes for SMSOTP

Optionally , you can configure back up codes when SMS OTP is disabled. To configure backup codes, follow the steps given below.

Adding OTP backup codes claim

  1. Navigate to Main menu -> Identity -> Claims -> Add -> Add Local Claim.

  2. Enter http://wso2.org/claims/otpbackupcodes as the value for Claim Uri.

  3. Add a Display Name and Description. For example, Backup Code.

  4. Enter postalcode as the value for Mapped Attribute.

  5. Select Supported by Default.

  6. Click Add.

allow-to-use-back-up-codes

Add backup codes for users

  1. Navigate to Main -> Identity -> Users and Roles -> List -> Users.

  2. Click User Profile of a preferred user and update the backup codes so that the user can disable SMS OTP by selecting Disable SMS OTP if required.

    Info

    A backup code can have any number of digits, and you can define many backup codes as comma separated values.

    define-backup-codes

Testing the sample

  1. To test the sample, go to the following URL: http://wso2is.local:8080/travelocity.com

    testing-travelocity

  2. Click the link to log in with SAML from WSO2 Identity Server.

  3. The basic authentication page will be visible. Use your WSO2 Identity Server credentials to sign in.
    basic-authentication-page

  4. You will get a token to your mobile phone.Type the code to authenticate, You will be taken to the home page of the travelocity.com app.

    Note

    If you do not have access to your mobile phone, you can use the backup codes defined for the user to authenticate the user and you are taken to the home page of the travelocity.com application

    authenticating-with-sms-otp travelocity-home-page

Top