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.
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
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
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
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.
allow-authentication-with-sso-for-second-factor
true
forceAuthN=true
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.
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
The following configuration options are available:
false
disable-recovery-codes
0
Allowed Second Factors