Contextual Multi-Factor Authentication (MFA)

Overview

FusionAuth applies multi-factor authentication (MFA) based on a number of configuration parameters and situational behaviors. In this document you’ll learn how and why FusionAuth challenges a user for another factor of authentication during the login process. Such a challenge might be entering a code sent to their email or entering a time based one-time password (TOTP) value.

If you are looking for guidance on implementing MFA using FusionAuth, please review the MFA guide.

MFA Inside The Authentication Process

There are four major considerations for whether MFA is applied during the login process.

• What is the MFA policy for the tenant or application?
• Does the user have MFA enabled? If this is not the case, then an MFA challenge is never triggered, but the user may be prompted to set up MFA, based on the tenant or application MFA policy.
• Did the user log in using an Identity Provider such as Google or OIDC? In this case, MFA is never required for the user.
• Has the device passed appropriate contextual checks such as being on a known device?

Here’s a high level diagram of the logic:

High level diagram of MFA logic.

Contextual Checks

The contextual checks are based on attributes of the request evaluated every time an authentication happens and and include:

• Has this device been seen before?
• Has this user been seen before on this device?
• Is there a suspicious login detected for this authentication attempt?

The duration of trust of the device can be configured with the tenant.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds configuration value.

The goal of this contextual check is to challenge the user for another factor of authentication whenever FusionAuth determines the risk of invalid access is higher than the user friction.

Depending on your license, you can configure MFA policies at both the tenant and application level. Let’s take a look at each of these in more depth.

Tenant Level MFA Configuration

Tenant level configuration applies to all applications within a tenant. The MFA policy has three values:

• Disabled, where no MFA challenge occurs
• Enabled, where an MFA challenge occurs if the user has a valid MFA method, and if they don’t, there is no MFA challenge
• Required, where an MFA challenge occurs and if the user doesn’t have a valid MFA method they are required to set one up

Here’s a diagram of the MFA challenge logic when the tenant has a policy for MFA.

Diagram of tenant MFA decision logic.

Application Level MFA Configuration

Application level configuration applies to a single application within a tenant. Application policies always supersede the tenant policy.

With an active application MFA configuration, there is an MFA policy with three possible values:

• Disabled, where no MFA challenge occurs
• Enabled, where an MFA challenge occurs if the user has a valid MFA method, and if they don’t, there is no MFA challenge
• Required, where an MFA challenge occurs and if the user doesn’t have a valid MFA method they are required to set one up

But there is an additional trust policy, which determines if an application accepts the results of other MFA challenges. The options here are:

• Any, where any application’s challenge results are acceptable
• This, where this application’s challenge results are acceptable, and any other application’s are not
• None, where no application’s challenge results are acceptable, and the MFA challenge will always be given

Here’s a table outline possible scenarios for different trust policies.

Here’s a diagram of MFA challenge logic when the application has a policy for MFA.

Diagram of application MFA decision logic.

License Limitations

Not all plans support all MFA features. The plan you are on affects the MFA options available to you and your users. Learn more about plan features and pricing.

The following contextual MFA features are limited to the specified plan.

Enterprise Only

• Application MFA policies
• Suspicious Login Contextual Check

Any Paid Plan

• Email MFA
• SMS MFA
• User MFA Enrollment Account Management Pages

Any Plan

• TOTP MFA
• Tenant MFA policies
• User MFA Enrollment APIs
• Application MFA policies for the FusionAuth Admin UI only

MFA Challenges After Identity Provider Login

If a user logs in with an Identity Provider such as Google or OIDC, FusionAuth does not challenge for MFA. FusionAuth trusts that the correct MFA challenge process happens at Identity Provider.

There’s an open issue to add a policy to allow for more control in this scenario.

Enforcing MFA Challenges On Certain Users

You may need more granularity on who is challenged for an additional factor during login.

For example, you might want everyone who is a member of a certain group or who has a certain user.data field to go through MFA. While there’s an open GitHub issue to enhance the flexibility of the MFA process by using a lambda, you can also accomplish this now.

Let’s use the example of making sure everyone in the mfa_required group is challenged whenever they log in, and no one else is.

These two options rely on different aspects of the challenge decision trees outlined above.

Use a Webhook

• Set a tenant or application policy to Enabled and then use the API to ensure that everyone in the mfa_required group has an MFA method.
• Use a transactional user.update webhook to ensure that the MFA method can’t be removed while the user is in that group.
• Set the trust duration to be the same or less than your session length.
• If you are using the application policy, set the trust policy to This.

Redirect Users Through a Special Application

• Create an “MFA check” application with an MFA policy of Required and a trust policy of None.
• After a user logs in, examine their profile on an interstitial page.
  • If they are in the mfa_required group, redirect them to this application. They will be prompted for MFA and then redirected to the initial application.
  • Users that are not in the mfa_required group can be sent directly through to the application.

Make sure the MFA check application uses a lambda to set the aud and applicationId claims to values expected by any access token consumers.

This is similar to doing a conditional step-up authentication on the interstitial page but avoids using the step up API.

MFA Challenges Outside Of The Login Process

If you need to prompt for MFA outside of the login process, you want to use step up authentication. For example, if you want to challenge for MFA when a user performs a high-risk action like initiating a money transfer. Use the APIs to perform this process.

Learn more about step up authentication.

Limitations On MFA Challenges

There’s an open issue about unexpected MFA behavior and workarounds when a user logs in with an identity provider but SSOs to an application with a login policy of Required.

If a user signs up with an MFA method that is allowed for a tenant, such as email, and the tenant configuration changes later to disable that MFA method, the user can still use that MFA method. Users cannot, however, add disabled MFA methods. If you are disabling an MFA method previously in use, it’s recommended you search for users using that method and remove it using a script and updating each user.