Skip to content

Add SMS OTP Login

SMS OTP (One-Time Password) is a security mechanism where a password, valid for a short duration, is sent to the user's registered mobile number. This password must be entered during the login process.

This method can be used as a form of passwordless authentication, allowing users to log in by providing a one-time passcode received via SMS on their mobile phones, instead of using a traditional password.

To configure SMS OTP as a passwordless authentication mechanism in WSO2 Identity Server, follow the instructions given below.


Set up SMS OTP

WSO2 Identity Server has some default settings for SMS OTP, which are sufficient for most cases. If required, you can change the default settings, as explained below.

To update the default SMS OTP settings:

  1. On the WSO2 Identity Server Console, go to Connections and select SMS OTP.
  2. Update the following parameters in the Settings tab: Setup SMS OTP in WSO2 Identity Server
    Field Description
    SMS OTP expiry time Specifies the expiry time of the OTP. The generated OTP will not be valid after this expiry time.
    Use only numeric characters for OTP Specifies whether to use only numeric characters in the OTP. If this is selected, the generated OTP contains only digits (0-9). If this option is not selected, the OTP will contain alphanumeric characters.
    SMS OTP length Specifies the number of characters allowed in the OTP.
  3. Once you update the SMS OTP settings, click Update.

Configuring SMS Providers

Configurations related to SMS providers are located under the Email & SMS section On the WSO2 Identity Server Console.

Supported Providers

WSO2 Identity Server supports Twilio, Vonage, or custom SMS providers by default. To learn how to configure each provider, please see the relevant section.

Configuring Twilio

To configure Twilio as your SMS provider, follow the steps below:

  • Go to Twilio and create an account.
  • After signing up for your 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".
  • After signing up, navigate to the Phone Numbers page in your console and note the phone number’s capabilities.
  • Get your first Twilio phone number and use that as the “Sender” in the settings. For more information, see this tutorial in the Twilio documentation.
  • Copy the Account SID and Auth Token from the Twilio console dashboard.
  • Go to SMS Provider section in the WSO2 Identity Server Console and click the Twilio tab and fill the required fields.

Name Description Example
Twilio Account SID Account SID received in the previous step. YourAccountSID
Twilio Auth Token Auth token received in the previous step. YourAuthToken
Sender Phone number that you received when creating the Twilio account. +1234567890

Configuring Vonage

To configure Vonage as your SMS provider, follow the steps below:

  • Login to Vonage and create an account.
  • Fill in the required fields and create the account.
  • Login to the Vonage dashboard and copy the API Key and API Secret.
  • Go to SMS Provider section in the WSO2 Identity Server Console and click the Vonage tab and fill the required fields.

Name Description Example
Vonage API Key Use the API Key from the previous step. YourAPIKey
Vonage API Secret Use the API Secret from the previous step. YourAPISecret
Sender The number that the receiver will see when you send an SMS. +1234567890

Configuring a Custom Provider

If you are not using either Twilio or Vonage as the SMS provider, you can configure a custom SMS provider. Custom SMS provider configuration will pass the SMS data to the given URL as an HTTP request.

To configure a custom SMS provider, in the SMS Provider section click the Custom tab and fill the required fields.

Name Description Example
SMS Provider Name Display name for the SMS provider. MySMSProvider
SMS Provider URL URL of the SMS gateway where the payload should be published.
Content Type Content type of the payload. Possible values are JSON or FORM (Optional). JSON
HTTP Method HTTP method that should be used when publishing the payload to the provider URL. Possible values: PUT, POST (Optional). POST
Payload Template How the payload template should be.
{{body}} - Generated body of the SMS. (Example - This can be the OTP).
{{mobile}} - Number that this sms should be sent to.
Example JSON payload template:
{“content”: {{body}},“to”: {{mobile}}}}

({{mobile}} and {{body}} will be replaced with the corresponding values at the runtime.)
Headers Custom static headers need to be passed. If multiple headers need to be passed, they should be comma separated. (Optional) authorisation: qwer1234asdfzxcv, x-csrf: true, x-abc: some-value

Enable SMS OTP Login for Your App

Follow the steps given below to add SMS OTP login to the login flow of your application.

  1. On the WSO2 Identity Server Console, go to Applications.

  2. Select the application to which you wish to add SMS OTP login.

  3. Go to the Login Flow tab of the application and add SMS OTP login as follows:

    1. Go to Predefined Flows > Basic Flows > Add Passwordless login.

    2. Select SMS OTP.

    3. Click Confirm to add passwordless login with SMS OTP to the sign-in flow.

      Configuring magic link login in WSO2 Identity Server using the Visual Editor

  4. Click Update to save your changes.

Try It Out

Follow these steps to test the SMS OTP login:

  1. Visit the application URL.
  2. Click Login to bring up the WSO2 Identity Server login page.
  3. On the login page, enter your username and click Continue.

    Sign In with SMS OTP in WSO2 Identity Server

    This action redirects you to the SMS OTP page.

    SMS OTP submit page

  4. Check your phone for the SMS containing the one-time passcode.

  5. Enter the received passcode on the SMS OTP page and click Continue.