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. 104 Adding a second factor for the first time


Fig. 105 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. 106 Entering management mode


Fig. 107 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. 108 Receiving recovery codes during sign up


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. 109 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. 110 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. 111 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
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
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.