Multi-factor Authentication

Multi-factor Authentication (MFA) is an authentication method that requires users to provide two or more verification factors to gain access to a resource. Enabling MFA on your site with ReachFive ensures your users must verify their login with a second factor (sms code, email link, etc.).

Why use MFA and Stepup authentication?

One of the best benefits of MFA with ReachFive is that it improves your organization’s security by requiring users to identify themselves with more than just a username and password when logging into their account or accessing specific resources. Traditional credentials are great, but they can be vulnerable to brute force attacks.

When you enable MFA on your ReachFive account, it ensures your users that their experience is secure while extensively reducing the chances of their private information being stolen.

See the MFA methods in the Core SDK or the MFA endpoints in our Identity API for more information on using the MFA flow.

Prerequisites

In order to use MFA, you must have the following features enabled and configured on your account:

Using phone numbers for MFA

The SMS feature is not required for MFA. However, if the feature is not enabled, a few conditions apply.

When does this apply? 🤔

If you only use email as the second factor, there is no need for the SMS feature.

You can also use phone_number as the second factor without SMS enabled. However, in this case, some conditions apply:

  • Phone number verification: When the SMS feature is disabled, phone_number_verified is always false, even if the same number is used as an MFA credential.

  • SMS provider configuration: You can configure an SMS provider, but templates unrelated to Passwordless or MFA remain disabled.

  • Independent MFA credentials:

    • Updating a phone_number does not update the associated MFA credential.

    • Adding a phone_number as a credential does not automatically mark it as verified.

MFA settings

You can manage your MFA settings directly in the ReachFive Console.

Enable second factors for MFA

You can enable both email and SMS (or just one) as a second factor for your users to use in the MFA/stepup flow.

  • Email = This means that you users can use their email as the second factor in the MFA flow (and will receive an email with the link or verification code as part of that flow).

  • SMS = This means that you users can use their mobile as the second factor in the MFA flow (and will receive an SMS with the verification code as part of that flow).

To enable the second factors:

  1. From your ReachFive Console, go to MFA  Settings.

  2. Toggle the second factor that you would like to enable.

  3. Don’t forget to Save your input.

Require MFA for login

It’s possible to enforce MFA all the time for the login flow if desired for users with a registered second factor MFA credential.

This is only enforced when users have a registered second factor credential for MFA. If they do not have a credential registered, then the stepup is not required for that user to log in.
Options
Option Notes

Always

Users are always required to validate a second factor to log in.

Never

Users are never required to validate a second factor to log in.

To set the requirements for logging in:

  1. From your ReachFive Console, go to MFA  Settings.

  2. Choose Always or Never.

  3. Don’t forget to Save your input.

    mfa settings require MFA always

Stepup authentication

Stepup authentication is a little different than traditional MFA, but it offers a balance between unnecessary friction in the user experience and enhanced security when accessing sensitive information.

You must have MFA enabled on your ReachFive Console to use Stepup authentication.

There are two subsections here:

Stepup authentication is best used for specific actions such as:

  • Paying with a credit card

  • Changing personal account details

  • Adding authentication information

  • Logging in from a new device or location

These are just examples and don’t represent all possible times you might use Stepup authentication.

MFA flow with Stepup authentication

When a user is already logged in, but they want to access something secure or perform a sensitive action (like purchasing a product), you can configure the Stepup authentication flow. See the accompanying MFA flow table to follow along with the flowchart.

The flow below assumes the user has already signed up to your site.

stepUpFlow

MFA Flow table
Step Core JS SDK method API operation Notes

1

loginWithPassword

User logs in

User logs into the site.

The user can log in other ways than just using a password of course. See the other options in the Core SDK method list.

2

User browses the site; visits a product page.

3

listMfaCredentials

List MFA credentials

Ensures the user has MFA credentials and has completed the registration process.

This can be via mobile phone or email.

4

startMfaPhoneNumberRegistration

Start MFA registration

Registers the user’s phone number for use as an MFA credential (second factor). You can also choose to trust a device while registering so long as the device is verified through this flow.

This step shows registering with a phone number, but you can also register with an email.

5

verifyMfaPhoneNumberRegistration

Verify MFA registration

Verifies the user’s phone number for use as an MFA credential (second factor). You can also choose to trust a device while registering so long as the device is verified through this flow.

This step shows verifying a phone number, but you can also verify an email.

6

getMfaStepUpToken

Initiate stepup flow

Initiates the stepup flow.

7

startPasswordless

Start Passwordless MFA

Starts the passwordless flow for MFA using the step_up token received in the stepup flow initiation.

8

verifyMfaPasswordless

Verify Passwordless MFA

Verifies the passwordless flow for MFA with the user verification code and challenge_id.

9

exchangeAuthorizationCodeWithPkce

Retrieve access token

Exchanges the authorization code for a new access token.

10

Decode the token

Confirms "mfa" is part of the user’s "amr" array.

{
    ...
    "amr": [
        "mfa",
        "sms"
    ]
}

11

Product purchased.


Using the stepup endpoint

When you use the stepup endpoint to initiate the stepup flow, you can start the flow in one of three ways.

See the table below for accompanying details to the flowchart.

stepUpFlowEndpointScenarios

Stepup options
Approach Description

SSO session cookie

Recommended

Using a current, active SSO cookie initiates the stepup flow.

With the SSO session cookie, the cookie is deposited by the SDK into the browser. This way, it can’t be leaked or used on another domain.

It only works in conjunction with the Core SDK.

Example

POST https://YOUR_DOMAIN/identity/v1/mfa/stepup

SESSION_COOKIE

{
  "client_id": "nvR2y0ks...EgCW2dqy",
  "response_type": "code",
  "scope": "openid phone address profile mfa",
  "redirect_uri": "https://redirect_uri.com/"
}

tkn in request body

Recommended

Passing a valid tkn in the request body initiates the stepup flow. The tkn comes from the user login. Essentially, users must log in to have a fresh authorization.

Example

POST https://YOUR_DOMAIN/identity/v1/mfa/stepup

{
  "client_id": "nvR2y0ks...EgCW2dqy",
  "response_type": "code",
  "scope": "openid phone address profile mfa",
  "redirect_uri": "https://redirect_uri.com/",
  "tkn": "xhNGxw...70zx32" (1)
}
1 The one-time use authentication token.

access_token in AUTH header

Passing the access_token in your Authorization header initiates the stepup flow.

We recommend that you only use this approach if you are unable to use the SSO session cookie or tkn approach.
We can’t ensure how fresh the token will be in this case or if it has been leaked. Therefore, we strongly recommend against using this approach. It should be implemented as a last resort only.

Example

POST https://YOUR_DOMAIN/identity/v1/mfa/stepup

AUTHORIZATION: Bearer {access_token}

{
  "client_id": "nvR2y0ks...EgCW2dqy",
  "response_type": "code",
  "scope": "openid phone address profile mfa",
  "redirect_uri": "https://redirect_uri.com/"
}

MFA user experience

By enabling MFA with ReachFive on your site, you can provide a secure, frictionless user experience.

A typical user journey is when Stepup authentication is configured so that MFA is only required during sensitive actions like making a purchase or changing personal details, similar to the video below.

You can configure a template that is sent to users like in this experience on the ReachFive Console.