The Conditional Multi-Factor action adds a condition after the authenticator has run. The condition decides if additional factors are required. This means it is a dynamic way of adding additional factors to the authentication.
It can be configured to operate in three different condition modes:
The Attribute Enable Condition mode runs a predefined second factor if the condition is met.
The condition is an attribute from the authenticator or previous actions that is set to true. When true, the MFA action will run that second factor before letting the user through.
The attribute the action looks for by default is named requireSecondFactor but can be configured to any attribute name. The location from where that attribute is retrieved can also be configured to be subject-attributes (the default), context-attributes, or action-attributes.
requireSecondFactor
subject-attributes
context-attributes
action-attributes
A common use is to configure another action before the Conditional Multi-Factor action to look up an attribute about the user. If the requireSecondFactor has the value true the second factor is triggered.
true
The second factor to use when condition is true is statically configured on the action along with the attribute name to look for.
Fig. 99 Configuration of the Attribute Enable Condition
With the Attribute ACR Condition mode, you allow the user to configure their preferred second factor. This is done out of band, and placed in a data source or other place where the actions can find the attribute.
Example: The user wants SMS to always be enabled as a second factor when logging in. This can be achieved by adding the ACR for the SMS authenticator configured to the users data. By default the Conditional Multi-Factor action looks for the ACR in the attribute named secondFactorAcr (this can be changed via configuration). The location from where that attribute is retrieved can also be configured to be subject-attributes (the default), context-attributes, or action-attributes.
secondFactorAcr
When that attribute is found, the ACR is looked up, and if it matches an existing authenticator, it will be triggered. If there is no authenticator matching the ACR, the action will fail and the user will not be able to log in.
Important
If the ACR found for a user does not exist in the current configuration the authentication for that user will fail.
Only the attribute name to look for is needed for configuration. By default it is set to secondFactorAcr. The authenticator to run is taken from this ACR value and matched against available authenticators in the profile.
Fig. 100 Configuration of the Attribute ACR Condition
In the Subject Condition mode the username (subject) is matched against a set of regular expressions. Each condition has an associated authenticator that will run when the condition matches. Only the first matching condition will run, so order is important.
This can be useful when authenticating internal and external users with the same flow. External users could be configured with a different second factor than internal users.
Another use-case is when separating username and password in two different authenticators. Depending on the username the password may need to be validated against different backend. By matching on the username, we can call a second factor that verifies the password against the relevant source.
An ordered list of regular expressions and what authenticator to run when a match is found.
Fig. 101 Configuration of the Subject Condition
In the Client Property Condition the OAuth client that initiated the authentication flow can be ued to prompt for different second factors. These conditions are made up from a set of expressions paired with an authenticator. The first expression to evaluate to true will be selected, and its corresponding authenticator will be executed.
This could be useful when grouping clients in external and internal groups, and allow them to use different second factors. This example could be configured like this:
external
internal
client.properties.group === 'external'
client.properties.group === 'internal'
All clients with a property of group with the value external will be prompted by the TOTP authenticator, and clients with the value internal would be prompted with the SMS authenticator. Any client without the group property would fail, so a “catch all” condition is advised.
group
The client object has the following members:
id
name
properties
requires_consent
is_public
By default, this action checks that the subject name produced by the second factor authentication is equal to the currently authenticated subject name (the subject produced by the first factor). If these subjects are not equal then this action returns a failed result and the overall authentication does not succeed.
This default behavior is the safest one since in most cases both the first factor subject and the second factor subject need to match. However, there may be cases where these subjects can be different. For those specific cases, the disable-second-factor-subject-check config property can be set to true, resulting in the subject check not being performed and different first factor and second factor subjects being allowed.
disable-second-factor-subject-check
Only use disable-second-factor-subject-check when the action usage scenario allows for different first factor and second factor subjects, typically because the association between these different subjects is checked or enforced somewhere else.