Configuring SMS OTP

The SMS provider is the entity that is used to send the SMS. WSO2 IS supports most of the SMS APIs. Some use the GET method with the client secret and API Key encoded in the URL, 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). Note that this could change significantly between different SMS providers. The configuration of the connector in the identity provider would also change based on this.

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

Deploying travelocity.com sample

Deploy the sample travelocity app in order to use it in 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 WSO2 Identity Server (IS).

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.
   For example, navigate to https://www.nexmo.com, and click the padlock next to the URL on Chrome.

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. In the Identity section under the Main tab of the management console, click Add under Identity Providers.

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.

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

11. Click Register.

Configuring the service provider

The next step is to configure the service provider.

1. Return to the WSO2 IS management console.

2. In the Identity section under the Main tab, click Add under Service Providers.

3. Enter travelocity.com in the Service Provider Name text box, and click Register.

4. In the Inbound Authentication Configuration section, click Configure under the SAML2 Web SSO Configuration section.

   1. Now set the configuration as follows:

      1. Issuer: travelocity.com

      2. Assertion Consumer URL: http://wso2is.local:8080/travelocity.com/home.jsp
         Click Yes, in the message that appears.

   2. Select the following check-boxes:

      1. Enable Response Signing

      2. Enable Single Logout

      3. Enable Attribute Profile

      4. Include Attributes in the Response Always
         

   Open

   

5. Click Update to save the changes.
   Now you are sent back to the Service Providers page.

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

   Open

   

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

8. 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 as this field is empty by default if you are creating the user using the WSO2 IS management console..

1. Select List that is under Users and Roles, and click Users in the IS Management Console.

2. Click User Profile of the user you want to edit and update the mobile number.
   The mobile number needs to be in the format given in the samples of the SMS provider. For example, 94778888888. 
   If the format is wrong you would not get the text message with the code to sign into WSO2 IS.

   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.

3. Enter the First Name for the user and click Update.