Configuring WSO2 SMSOTP Connector

This topic provides instructions on how to configure the SMSOTP and the Identity Server to integrate using a sample app. This is an updated version of the WSO2 article found here. The current SMSOTP connector can be easily used with nexmo but difficult to integrate with other SMS APIs. I have updated the connector to be easily integrable with most SMS APIs on the market. This is the updated documentation of the connector. 

Building the SMSOTP artifacts

1. Clone the repository from https://github.com/Pulasthih/is-connectors
2. Navigate to components/smsotp and build the two artifacts using mvn clean install.

Deploying SMSOTP artifacts

1. Place the smsotpauthenticationendpoint.war file into the <IS_HOME>/repository/deployment/server/webapps directory.
2. Place the  org.wso2.carbon.identity.authenticator.SMSOTP-1.0.0.jar file into the <IS_HOME>/repository/components/dropins directory.

Configuring the SMSOTP provider

The SMS provider is the entity that will be used to send 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 being encoded in the URL (eg: Nexmo) whereas some may use the POST method while sending the values in the headers and the message and telephone number in the payload (eg: Clickatell). Note that this could change significantly between different SMS providers. The configuration of the Identity Server would also change along with this.

Deploying travelocity.com sample

The next step is to deploy the sample 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 service provider.

Configuring the identity provider

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

1. Download the WSO2 Identity Server from here and run it.
2. Log in to the management console as an administrator.
3. In the Identity section under the Main tab of the management console, click Add under Identity Providers.
4. Give a suitable name (eg: SMSOTP) as the Identity Provider Name.
5. Go to SMSOTP Configuration under Federated Authenticators .
6. Select both checkboxes to Enable SMSOTP Authenticator and make it the Default .
7. Enter the SMS Url and the HTTP Method used (eg: GET or POST). Include the headers and payload if the API uses any. If the text message and the phone number are passed as parameters in any field, then include them as &msg and &num respectively.

Note: If nexmo is used as the SMS provider, the nexmo API requires the parameters to be encoded in the URL, so the SMS URL would be as follows,

https://rest.nexmo.com/sms/json?api_key=*********&api_secret=********&from=NEXMO&to=&num&text=&msg

*The api key and api secret are provided when you register with nexmo.

Note: If clickatell is used as the SMS provider, clickatell uses a POST method with headers and the text message and phone number being 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”:”&msg“,”to”:[“&num“]}

*The auth token is provided when you register with clickatell.

8. Click Register .

You have now added the identity provider.

Configuring the service provider

The next step is to configure the service provider.

1. Return to the 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.

5. Now set the configuration as follows:

• Issuer : travelocity.com
• Assertion Consumer URL : http://localhost:8080/travelocity.com/home.jsp

6. Select the following check-boxes:

• Enable Response Signing
• Enable Single Logout
• Enable Attribute Profile
• Include Attributes in the Response Always

7. Click Update to save the changes. Now you will be sent back to the Service Providers page.

8. Go to Claim configuration and select the mobile claim.

9. Go to Local and Outbound Authentication Configuration section.

10. Select the Advanced configuration radio button option

11. Add the basic authentication as first step and SMSOTP authentication as second step

You have now added and configured the service provider.

Configuring User Claim

1. Select Users and Roles in the IS Management Console
2. Go to Users → admin →User Profile  and  update the mobile number. ( If nexmo is used, this number must be registered with nexmo in order to send sms).

Testing the sample

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

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

3. Basic authentication page will be visible, use your IS username and password.

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