Configuring SMS OTP¶

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

This document explains how to configure the SMS OTP connector with WSO2 Identity Server.

Let's get started!

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
usecase = "local"
secondaryUserstore = "primary"
SMSOTPMandatory = false
SendOtpToFederatedMobile = false
federatedMobileAttributeKey = "mobile"
CaptureAndUpdateMobileNumber = true
SendOTPDirectlyToMobile = false
redirectToMultiOptionPageOnFailure = false
TokenExpiryTime = 12

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 import 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:
       
    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://www.clickatell.com/sign-up/ 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.
       

    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".

    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. Navigate to Main tab -> Identity -> Service Providers -> Add.

2. Give a suitable name (e.g., saml-dispatch) as the Service Provider Name.

3. Configure Inbound Authentication for the service provider. For instructions, see Configuring Inbound Authentication for a Service Provider

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

   

5. 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.

      

6. 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.

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.

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.