SMS authentication

For SMS, the user does not have to install an app on their mobile device. The website initiates the mobile authentication at the OneWelcome Identity Platform, which sends a text message with a code to the user. The website then needs to present a screen where the user can enter the code that was sent via SMS. When the user enters the code, the website sends this to the OneWelcome Identity Platform, which returns the validation result.

General configuration

Go to the General subsection in General mobile config section to configure the following options.

The check box at SMS Authentication / Authentication enabled must be selected to allow mobile authentication via SMS. All SMS messages are sent from a pre-configured phone number. You can override this phone number by entering your own sender ID. This can be a phone number, a short code that is registered with your SMS provider, or an alphanumeric sender ID (such as your brand name).

Some countries do not support sending SMS messages from an alphanumeric sender ID, while other countries require you to register the sender ID up front. When sending the text message fails with this sender ID, the OneWelcome Identity Platform tries to send the SMS message from the default phone number.

The enrollment options are not necessary for SMS.

Mobile authentication type configuration

Go to Configuration → Mobile authentication → Mobile authentication types.

The following fields are required:

• Name: This is used to identify the type when calling the mobile authentication API

• Authentication method: SMS

• Max allowed resends: This is the maximum number of times an SMS message with the code can be sent for a single mobile authentication transaction. 0 means that resending the SMS message is not allowed.

• Request expires in: This is the time the user gets to complete the authentication via OTP.

• Max allowed attempts: This is the maximum number of times a user can enter an incorrect code to validate the transaction. When the user exceeds this limit, the transaction is invalidated. 0 means unlimited attempts. It is a best practice to set a limit.

Optional configuration:

• SMS sender ID: Text messages are sent from the phone number that is configured for the SMS provider. You can configure a specific sender per mobile authentication type. This can be a phone number, a short code that is registered with your SMS provider, or an alphanumeric sender ID (such as your brand name). Some countries do not support sending SMS messages from an alphanumeric sender ID, while other countries require you to register the sender ID up front. Configuring the sender ID per mobile authentication type is optional. When sending the text message fails with the sender ID for this mobile authentication type, the OneWelcome Identity Platform retries sending the SMS using the sender ID that is configured in as sender ID in the general configuration. When that fails, it tries to send the message using the default phone number for the OneWelcome Identity Platform.

• Default messages: You can pre-configure the message that is sent to the user via SMS per supported language. Refer to SMS message body for their format.

SMS message body

With SMS authentication, the user receives a six-digit code. This code must be included in the message. This message can be configured up front or sent with the API request that triggers the mobile authentication. A placeholder must be included to indicate where the code should be inserted in the message.

The placeholder to use is {code}. If the {code} placeholder is not included in the message, the OneWelcome Identity Platform only sends the code in the text message and no additional message.

Example SMS message: Your example SMS code: {code}.

The OneWelcome Identity Platform sends SMS messages for one-time codes. There is a (proposed) standard for sending one-time codes via SMS. Some browsers suggest using the code that was sent for that domain. For the autocomplete, the message must end with the following:

• a newline
• @ plus the host name of the website where the user enters the code, such as @www.example.com
• # plus the code: #code

Your verification code is: {code}

@www.example.com #{code}