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.).

Prerequisites

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

See the MFA methods in the Core SDK or the MFA endpoints in our Identity API for more information on using the MFA flow.
Why use MFA and Step-up 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.

Step-up authentication

Step-up 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 Step-up authentication.

There are two subsections here:

Step-up 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 Step-up authentication.

MFA flow with Step-up 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 Step-up 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.
diagram
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).

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).

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

Introspect 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.
diagram
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/"
}

Configure MFA SMS template

You can configure the SMS template that users receive when wanting to use MFA for both activation and the step-up process.

The MFA feature must be enabled on your ReachFive Console. Contact support if you would like the MFA feature.

Instructions

  1. Log in to your ReachFive Console.

  2. Go to MFA  <Type  sms templates.

    Where <Type> is Activation or Step-up.

  3. Enter the Verification Code Lifetime.

    This specifies the validity period for the code in seconds.

  4. Enter your Message.

    Currently, the following variables are available using liquid:
    Variable Description

    {{verification_code}}

    This is the generated verification code sent by the SMS. In other words, this is how long the user has to use the code.

    Users enter this code as part of the MFA or Step-up authentication flow.

    {{user.phone_number}}

    The user’s email address.

    {{user.given_name}}

    The user’s given name (first name).

    example

    Nicole Dubois

    {{user.family_name}}

    The user’s family name (last name, surname).

    example

    Nicole Dubois

  5. Don’t forget to Save your input.

Configure MFA Email template

You can configure an Email template that users receive when wanting to use MFA for both activation and the step-up process.

This will not be sent to verified emails.
The MFA feature must be enabled on your ReachFive Console. Contact support if you would like the MFA feature.

Instructions

  1. Log in to your ReachFive Console.

  2. Go to MFA  <Type  email templates.

    Where <Type> is Activation or Step-up.

  3. Enter the sender email in the From field.

  4. Enter your Subject.

    You can use Liquid variables here.

  5. Enter the Redirect to URL. This is where users are sent after clicking the magic link.

  6. Enter how long you want (in seconds) the link be valid in the Link Lifetime field.

  7. Enter your Message.

    You can use Liquid variables here.

  8. Optionally, toggle the HTML? slider if you want the email to be sent in HTML.

  9. Don’t forget to Save your input.

Liquid variables

The following variables are available using liquid.

Variable Description

{{verification_code}}

This is the generated verification code sent by the SMS. In other words, this is how long the user has to use the code.

Users enter this code as part of the MFA or Step-up authentication flow.

{{link}}

This is the magic link sent in the email to verify their email address.

After ther user clicks this link, they are directed to the address entered as part of this template.

{{user.lang}}

The user’s language.

{{user.email}}

The user’s email address.

{{user.given_name}}

The user’s given name (first name).

example

Nicole Dubois

{{user.family_name}}

The user’s family name (last name, surname).

example

Nicole Dubois

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 Step-up 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.

Configure the SMS template that is sent to users in this experience on the ReachFive Console.