Skip to main content

​
Prerequisites

Before you can add MFA to Stytch’s pre-built UI, you’ll need to complete the following steps:
1

Build out primary authentication

Before integrating MFA, you need to already have a primary authentication flow built out. You can do so by following one of the integration guides:

Email Magic Links

OAuth

SSO

2

Configure enforced MFA for an Organization

To configure MFA, you’ll need to first toggle on “Require MFA” for at least one Organization in the Stytch Dashboard, or call the Update Organization API with mfa_policy set to REQUIRED_FOR_ALL.Each Organization is can specify which mfa_methods are allowed for Members in their Organization: either ALL_ALLOWED or RESTRICTED. If RESTRICTED, Members can only use MFA methods specified in the allowed_mfa_methods array.For example, if an Organization requires Members to use TOTP MFA:
{
    "mfa_policy": "REQUIRED_FOR_ALL",
    "mfa_methods": "RESTRICTED",
    // Optional, not enforced if mfa_methods is ALL_ALLOWED
    "allowed_mfa_methods": ["totp"]
}

​
Integrating MFA

The UI component handles MFA enrollment and authentication automatically, honoring both the Organization’s MFA Policy and any optional Member enrollment. You can adjust the defaults for which MFA options are shown and the order they are presented to the end user through the mfaProductInclude and the mfaProductOrder arrays in the UI config. However, the Organization’s allowed_mfa_methods and the Member’s current MFA enrollment options will take precedence. 
var organizationConfig = {
  authFlowType: "Organization",
  mfaProductInclude: ['totp', 'smsOtp'],
  mfaProductOrder: ['totp', 'smsOtp'],
  ...,
};

​
Required MFA enrollment

When an Organization’s MFA Policy is set to REQUIRED_FOR_ALL but the Member is not currently enrolled in MFA, the UI will automatically prompt the user to enroll after primary authentication, via the flow shown below.
  • If neither the Organization nor UI config restrict the MFA methods available, the user will be presented with options ordered according to the mfaProductOrder array.
  • If the Organization restricts MFA methods, the UI will surface that option — even if it is not explicitly included in the UI config.
  • If the Organization does not restrict MFA methods and mfaProductInclude is explicitly passed in the UI config, the user will only be shown the options allowed by the config.