Opt-In MFA

The Opt-In MFA action allows the user to add second factors to protect their account. The first time the user hits the action they will be presented with the option to add a second factor. Once added, the user must always login with two factors. The user can choose to not opt-in (if so configured) and will be asked again at a later time.

Once a factor has been added, the user can add other factors in the management function of the action. An example setup could be to allow for SMS and WebAuthN to be used as second factors. The user might add SMS first, and then at a later stage decide to also add a Yubikey or fingerprint using WebAuthN.

All factors the user has enabled are stored on the user’s account along with hashed recovery codes. If the second factor is an external account that uses a different username (for example Google) then the external username will be linked with the factor on the account. This is not the same as Account Linking but an account local link for that factor only.

This action serves as a protection for the user’s credentials. Once enabled by the user it is not possible for the user to disable it again. The user can remove factors it no longer uses as long as there is at least one second factor remaining.

Registering a New Factor

When the user selects a method to register as a new factor, they will be prompted to authenticate with that method. This is a two-step process where the user is able to register the factor itself (such as adding a new yubikey) and then associating this factor with their account.


Fig. 110 Adding a second factor for the first time


Fig. 111 User selected WebAuthN and adds touch-id

Managing Factors

The user can select to manage their factors during login. The user will be asked to authenticate with an existing factor, or a recovery code to enter management mode. There the user can add or remove factors to their account. It is required to always keep at least one factor so a user will only be able to remove factors when there are two or more registered on the account.


Fig. 112 Entering management mode


Fig. 113 Adding another factor

Recovery Codes

The user will receive a set of recovery codes during the first sign-up. These are one-time passwords that the user receives when enabling MFA on their account. These can only be used to manage the account to replace lost factors with new ones. The user can also generate new batches of recovery codes from the opt-in management screen.


Fig. 114 Receiving recovery codes during sign up

Single Sign-On of second factors

By default, valid single sign-on (SSO) sessions for second factors are ignored by this action and an explicit second factor authentication is always required (if second factors are configured).

This behavior can be changed by assigning the allow-authentication-with-sso-for-second-factor configuration setting with true. In this case, if there is a valid and compatible SSO session for any of the registered second factors, the action will skip the second factor selection and authentication steps entirely. A side-effect of this behavior is that the user will be unable to manage their second factors during a flow where the second factor is skipped due to SSO, since the link to management appears in the skipped selection screen. A way to force the selection screen to appear is to start an authentication flow that requires fresh authentication (forceAuthN=true), since that disables the use of any existing SSO session created previously and will therefore show that selection screen.

Second factor authentication for registration or management purposes always ignores any existing SSO session and is therefore always requested to the user.


The action requires that any factor that is used for registration has the Action as a pre-requisite for registration. This mean that if the Authenticator is used in other registration flows it needs to either be updated to only be used as an opt-in factor or be duplicated. This is to ensure that there registration of second factors is protected properly.

Configuration in the Web UI


Fig. 115 Configuration screen for Opt-in MFA

The UI will warn if a factor already has a registration flow configured and let the admin decide between updating it or duplicating it.


Fig. 116 Prompt to decide if the registration should be updated or the authenticator should be duplicated

This will result in the selected factor having an action as pre-requisite for registration. In the example below, the WebAuthN authenticator is used in the Opt-in MFA action and thus have the pre-requisite set.


Fig. 117 WebAuthN used as a factor in Opt-in MFA with its pre-requisite set

Configuration Options

The following configuration options are available:

Configuration Mandatory Description
account-manager yes Where the user’s account is located
disable-recovery-codes yes Enable if the user should not be able to manage the additional factors using recovery codes, a user will be unable to login or manage the account if the ability to authenticate with any of the configured factors is lost.
allow-authentication-with-recovery-code yes Enable if user should be able to login with recovery codes. By default these are only possible to use to enter the management mode. Default false, setting should not be configured when disable-recovery-codes is enabled
allow-authentication-with-sso-for-second-factor no Enables the automatic completion of the second factor authentication step, skipping the second factor selection and authentication steps, if there is a valid Single Sign-On (SSO) session for any of the registered second factors. By default this option is disabled, meaning the user always have to authenticate with the second factor, even if there is an SSO session for it.
opt-out-ttl-in-days yes How many days to wait to ask again since the user last opted-out. 0 means opt out is disabled. Default 0.
allowed-second-factors yes A list of authenticators that the user can pick from. See below.
mfa-state-bucket no A bucket to use for the users state. If not configured, this state will be stored on the account. When using a LDAP data-source, this is required.

Allowed Second Factors

Configuration Mandatory Description
authenticator-id yes An authenticator that can be used as a second factor
description no A description that will be presented to the user for this factor, if not set the default id or description from the authenticator will be used.