SMS OTP

The SMS One Time Password (OTP) Authenticator, adds a factor of SMS to an authentication chain. It can be used standalone but in most cases it makes more sense to use it as a second or third factor in an authentication flow, or as an additional factor in a registration flow. The SMS OTP Authenticator can run in two modes. In non-smartphone capable OTP mode, or in Smartphone enabled Hyperlink mode.

The SMS OTP Authenticator supports the following capabilities:

  • SMS One Time Password sent as Text
  • SMS One Time Password sent as Hyperlink
  • Registration and update of a users phonenumber

Base Configuration

The Authenticator base configuration is found in the general section Authenticator Base Configuration.

Using as standalone factor (Single factor)

In some cases it’s necessary to use SMS as a single factor. In such cases the SMS OTP Authenticator will start by querying the user for it’s username.

../../_images/authenticate-enter-username.png

Fig. 88 SMS Authenticator - Enter username

If the username doesn’t exist, or the user doesn’t have a registered phonenumber the Authenticator will show the same error error.no-user-or-phonenumber.

../../_images/no-username-invalid-phone.png

Fig. 89 SMS Authenticator - Invalid phone number or username

Using as second or N-th factor

The most common case is to use the SMS OTP Authenticator as a factor in a multifactor authentication setup. Commonly after a first factor which collects a username and a password. The SMS OTP Authenticator will then bypass the step of collecting the username again, and will use the username it gets from the SSO Session already established by the previous factor.

See Multi-factor configuration for Authentication for how to configure a Multifactor authentication chain.

Using an Intermediate Attribute

You can configure the authenticator to pick up the value for the phone number from an attribute, by configuring intermediate-attribute-name, instead of using the account manager to fetch it from a database. It is mandatory that the referenced attribute exists in the intermediate attributes, so it has to be set by a previous authenticator or an authentication-action.

Note

It is not possible to enable registration while using this option

Caution

This option can only be used when the authenticator is not the first factor, it must either have a pre-requisite authenticator configured, or prompted from an authentication-action. Trying to use the authenticator as a single factor (or first factor) with an intermediate-attribute-name configured will result in an error.

SMS OTP in OTP mode

When using the Authenticator in OTP mode, the flow requires the user to manually read and enter a One Time Password (OTP) that the user has received on their phone, the default strength of the OTP is 6 digits and timeout 1 minute.

../../_images/authenticate-enter-otp.png

Fig. 90 SMS Authenticator - Enter OTP

Note

For testing purposes, the following system property may be used to tell Curity to use a hardcoded OTP value: se.curity:identity-server:unsafe:hardcoded-otp. This must not be used in production environments.

Localization

The SMS message sent to the users, can be customized and localized. The full message key is authenticator.sms.enter-otp.sms.sent.message with default value %s.

Important

If you modify the message, don’t forget to add %s wherever you want the OTP to be in the message.

Registration

The SMS OTP Authenticator supports phonenumber registration. This requires the Authenticator to be configured with an account manager that can update the phonenumber of the underlying account. Both the Standard SQL Account Manager and the SCIM Account Manager support this capability. The SMS OTP Authenticator restricts the user to have a single primary phonenumber registered with it’s account. It is not possible to have multiple numbers.

It is required to protect the registration by another factor. I.e. to not let the user change the phonenumber without being authenticated by some means. This is done by configuring the required-authenticator-for-registration setting in the general authenticator setting.

Typically best practice is to require another N-factor before letting a user change the phonenumber. This is to avoid potential attempts for an attacker to take over a user’s account by stealing less factors than the end-application requires. So if the SMS OTP is used in a 2-factor flow, the registration section should also require 2 factors in order for it to not allow a user to go from 1 factor to 2 factors.

If no other means of second factors are available, like Encap or BankID, then it is at least recommended to use the Email Authenticator as the second registration factor.

Registration during authentication

The Authenticator can be configured to allow the user to change or register their phonenumber under an ongoing authentication flow. This is done by configuring the allow-registration-during-login property of the authenticator. (Automatic Login)

By default this is enabled, which results in a button shown in each step, allowing the user to start the registration flow.

Show info before registration

When the user is about to register it’s phonenumber, we require the user first to authenticate. This can be confusing for the user since it may not be aware of what’s going on. For this reason it can be useful to show a informational page before the user starts the registration flow. By enabling show-info-before-registration the authenticator will redirect to the info page rather than the registration page, when the user clicks the registration button.

../../_images/info-screen1.png

Fig. 92 SMS Authenticator - Information screen

Automatic Login

When enabled, automatic login is available after successfully registering a new phone number.

Configuration

The general authenticator config is described under Authenticator Base Configuration. This section describes the additional parameters that are available for the SMS plugin.

Important

The SMS Authenticator is located in the configuration at /profiles/profile{id type}/settings/authentication-service/authenticators/authenticator{id}/sms

The available parameters for the SMS OTP Authenticator are

class sms
account-manager-id(ref, mandatory)

A reference to an account manager in the profile. This account manager must have a data-store configured for Registration to be possible. Otherwise the authenticator will operate in authentication mode only.

send-otp-as-code(boolean, default false)

This option sets the authenticator to use a One Time Password (OTP) instead of sending a Hyperlink when set to true.

opt-length(integer between 4 and 10, default 6)

This option sets the length of the OTP sent to the user. Only possible to set if send-otp-as-code is set to true.

allow-registration-during-login(boolean, default true)

Enables the registration button on the authentication screens, to allow the user to change or register a phone number during authentication

show-info-before-registration(boolean, default true)

Only possible to set if the allow-registration-during-login is set to true. This will show the info page before redirecting to the registration page.

max-allowed-attempts(integer between 0 and 100, default 3)

This setting restricts how many attempts a user can do to verify the OTP within a session. If the limit is reached, an error enter-otp.error.too-many-attempts will be shown. Setting this to 0, allows for unlimited attempts.

max-challenges-sent(integer between 0 and 100, default 3)

This setting restricts how many OTPs will be generated within a session. If the limit is reached, an error enter-username.error.too-many-attempts will be shown. Setting this to 0, allows for unlimited OTP generations. Whenever a new OTP is generated, the attempts counter is reset to 0.

Important

The SMS Authenticator requires an SMS provider to be configured on the profile. (Base Configuration of an Authentication Service Profile)

Example:

<authenticator xmlns="https://curity.se/ns/conf/profile/authentication">
        <id>sms1</id>
        <previous-authenticator>usernamePassword1</previous-authenticator>
        <required-authenticator-for-registration>encap1</required-authenticator-for-registration>
        <sms>
                <account-manager-id>SqlDSAccountManager</account-manager-id>
        </sms>
</authenticator>

A sms authenticator can also be used as a back-channel authenticator.

Example:

<authenticators>
  <backchannel-authenticator>
    <id>bankid-backchannel-test-authenticator</id>
    <sms-backchannel xmlns="https://curity.se/ns/ext-conf/sms-backchannel">
      <frontchannel-authenticator>sms1</frontchannel-authenticator>
    </sms-backchannel>
  </backchannel-authenticator>
</authenticators>