Two-factor and multi-factor authentication (2FA/MFA)

FoxIDs supports both a simple two-factor mode and an advanced multi-factor mode in the login authentication method.

Two-factor mode: Advanced multi-factor is disabled (default).
Multi-factor mode: Advanced multi-factor is enabled.

Use two-factor mode when one additional factor is enough. Use multi-factor mode when you need an ordered MFA chain or want to include authentication methods as MFA steps.

Concepts

Two-factor authentication (2FA) and multi-factor authentication (MFA) both add one or more verification steps after the primary sign-in.

2FA: a primary sign-in plus one additional factor.
MFA: a primary sign-in plus one or more ordered additional factors.

Supported factors

FoxIDs supports built-in factors and authentication methods as MFA items.

Factor	Type	AMR value
SMS code	Built-in	`sms`
Email code	Built-in	`email`
Authenticator app code	Built-in	`otp`
Recovery code	Built-in (authenticator app)	`otp`
Authentication method (OIDC, SAML 2.0, TrackLink)	Configurable item	Configured AMR, or method/profile name if empty

You can use any compatible authenticator app, for example Google Authenticator, Microsoft Authenticator, Authy, and other TOTP apps.

When MFA is required

MFA is triggered when one of the following applies:

The user has Require multi-factor (2FA/MFA) enabled.
The login authentication method has Require multi-factor (2FA/MFA) enabled.
The calling application requests MFA with ACR urn:foxids:mfa.

MFA requirements apply in both modes. If Advanced multi-factor is disabled, the requirement is fulfilled by the simple two-factor flow.

If specific ACR values are requested together with urn:foxids:mfa, only the matching ACR values are required.

Two-factor mode (Advanced multi-factor is disabled)

In this mode, built-in two-factor options are configured directly:

Authenticator app
SMS
Email

To configure two-factor mode:

Open the Authentication tab.
Click the Login authentication method to edit.
Click Show advanced.
Go to the Multi-factor section.
Keep Advanced multi-factor disabled and configure the Authenticator app, SMS, and Email options.

The authenticator app name shown to users can be configured. By default, the tenant name is used.

Configure simple two-factor options in login authentication method

SMS and email factors require user contact information. This can be provided as user identifiers or as claims (phone_number and email).

Two-factor selection behavior

In two-factor mode, FoxIDs prefers an already registered authenticator app. If no authenticator app is registered, SMS is preferred over email when both are available.

SMS two-factor enabled and user has phone number	Email two-factor enabled and user has email	User has registered authenticator app	Possible two-factor type(s)	Selected two-factor type
false	false	false	Authenticator app setup	Authenticator app setup
false	false	true	Authenticator app	Authenticator app
true	false	false	SMS, with optional authenticator app setup after SMS verification	SMS
true	false	true	SMS and authenticator app	Authenticator app
false	true	false	Email, with optional authenticator app setup after email verification	Email
false	true	true	Email and authenticator app	Authenticator app
true	true	false	SMS and email, with optional authenticator app setup after SMS or email verification	SMS
true	true	true	SMS, email, and authenticator app	Authenticator app

Multi-factor mode (Advanced multi-factor is enabled)

When Advanced multi-factor is enabled, MFA is configured as an ordered list of up to 5 MFA items.

To configure multi-factor mode:

Open the Authentication tab.
Click the Login authentication method to edit.
Click Show advanced.
Go to the Multi-factor section.
Enable Advanced multi-factor and configure the ordered MFA items.

Supported MFA item types:

Built-in:
- SMS
- Email
- Authenticator app
Authentication method:

Configuration rules:

Built-in item types can only be configured once each.
Authentication method items can be configured multiple times, for example with different profiles.
Items are executed in list order.
You can add, remove, and reorder items.

Configure advanced multi-factor item list with add/remove/reorder

MFA item AMR and ACR behavior

Each completed MFA item contributes AMR claim values to the session.

Built-in AMR values are fixed:
- SMS: sms
- Email: email
- Authenticator app and recovery code: otp
Authentication method item AMR:
- An optional custom AMR can be configured.
- If the AMR is empty, the authentication method name or profile name is used.

Requested ACR values are matched to MFA item AMR values in this format:

urn:foxids:<amr>
Example: urn:foxids:link

urn:foxids:mfa is the general MFA requirement, and FoxIDs adds AMR mfa when MFA is completed.

MFA item selection and chaining

If specific ACR values are requested, one of the matching MFA items must be completed.
If only general MFA is requested, any available configured MFA item can fulfill the requirement.
If more than one eligible MFA item exists and FoxIDs cannot auto-select one, a selection UI is shown.
If an authenticator app is configured and already registered, FoxIDs prefers it for general MFA requests.
If authenticator app setup is selected and not yet registered, the setup flow can continue after a selected SMS, email, or authentication method step.
If only the authenticator app is configured, setup can start directly after first-factor sign-in.

MFA authentication method page with optional authenticator app registration and the option to choose a different MFA item. MFA authentication method selection page

MFA SMS page with optional authenticator app registration and the option to choose a different MFA item.

MFA email page where the authenticator app is set up, with the option to choose a different MFA item.

MFA authenticator app page with the option to choose a different MFA item.

Authentication methods used as MFA items

Authentication methods (OIDC, SAML 2.0, TrackLink) can be used as MFA items with these rules:

MFA-specific ACR values are not forwarded to the MFA authentication method request.
The authentication method response must include the required AMR value for the selected MFA item.
The AMR value is normally added in the claim transform if the returned identity matches the expected identity. See the claim transform example.
If the required AMR value is missing, login fails.
After successful validation, FoxIDs adds AMR mfa to the resulting session.

Request MFA from applications

Applications can request MFA in both OpenID Connect and SAML 2.0.

If specific ACR values are requested but are not configured on MFA items in the selected login authentication method, authentication fails.

OpenID Connect

Use acr_values:

General MFA: acr_values=urn:foxids:mfa
General MFA and specific method: acr_values=urn:foxids:mfa urn:foxids:link

SAML 2.0

Use RequestedAuthnContext.AuthnContextClassRef:

General MFA: include urn:foxids:mfa
General MFA and specific method: include urn:foxids:mfa and specific values such as urn:foxids:link

Session behavior

FoxIDs validates required AMR values against the current login session.

New login: the session is created after all requirements are fulfilled.
Step-up login: an existing session is updated after all additional MFA requirements are fulfilled.
Session reuse: if the session already satisfies the required AMR values, FoxIDs reuses the session and does not prompt for login again.

Troubleshooting

Common reasons for MFA failures:

Requested ACR values are not configured as MFA items in the login authentication method.
An authentication method used as MFA does not return the required AMR value.
No configured MFA item is currently available for the user, for example because phone or email data is missing for SMS or email.