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 occursEnabled
, where an MFA challenge occurs if the user has a valid MFA method, and if they don’t, there is no MFA challengeRequired
, 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 occursEnabled
, where an MFA challenge occurs if the user has a valid MFA method, and if they don’t, there is no MFA challengeRequired
, 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 acceptableThis
, where this application’s challenge results are acceptable, and any other application’s are notNone
, 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.
Trust Policy | Example Application | Notes |
---|---|---|
Any | Apps in a suite of applications such as Google Drive, Google Calendar and Gmail | Any MFA challenge is good enough since they all have roughly the same risk profile. |
This | A gambling application which uses real money in a suite which has other fantasy gaming apps. | The other fantasy gaming apps might not require MFA at all, but if they do, it’s not a high enough level of security for the “real money” gambling application. |
None | An internal admin dashboard | Access should be strictly controlled and user friction is not an issue. |
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 themfa_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 ofNone
. - 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.
- If they are in the
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.