Stepup required

The following actions require users to go through the stepup flow:

Operation Notes

Update MFA email

In order to update an email that is used as a second factor for MFA, users must go through a stepup flow.

Delete MFA email

In order to delete an email that is used as a second factor for MFA, users must go through a stepup flow.

Update MFA phone number

In order to update a phone number that is used as a second factor for MFA, users must go through a stepup flow.

Delete MFA phone number

In order to delete a phone number that is used as a second factor for MFA, users must go through a stepup flow.

Add email as second factor for MFA or Add phone number as second factor for MFA

If there is already an existing MFA credential, users must go through the stepup flow to add a new MFA credential.

Login with password

If a user has an existing registered MFA credential and the MFA required setting is set to Always, a stepup is required to login.

This is not applicable to users without MFA credentials or if the MFA required setting is set to Never.

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/"
}

Retry MFA step-up

In some cases, a user may not receive the MFA verification code (for example, due to SMS or email delivery issues). To improve the user experience, the step_up token issued during the step-up flow can now be reused to request a new code. This allows integrators to implement a retry process without forcing users to repeat the full login or step-up flow.

The verification code requests in the MFA flow are subject to a limit. As soon as a new verification code is generated, the previous code becomes invalid. This limit helps protect against abuse and can be configured by ReachFive administrators. If you’d like details on the limit or to adjust this setting, contact your ReachFive representative.

retry token flow

Step-up MFA retry flow
Step Action Notes

1

Trigger step-up

Call POST /identity/v1/mfa/stepup with a valid tkn, SSO cookie, or access token to receive a step_up token.

2

Start passwordless MFA

Call POST /identity/v1/passwordless/start with the step_up token to send a verification code to the user.

3

Code not received?

If the user doesn’t receive the code, call POST /identity/v1/passwordless/start again with the same step_up token.

As soon as a new verification code is generated, the previous code becomes invalid.

4

Verify MFA

Once the user receives the code, call POST /identity/v1/passwordless/verify with the code and challenge_id to complete the flow.