Conditional Multi-Factor

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:

Mode Description
Attribute Enable Condition Checks for a boolean attribute and runs second factor if true.
Attribute ACR Condition Checks for an attribute containing an ACR, that ACR is used as the second factor.
Subject Condition Matches the subject against a rule-set. Picks second factor based on the rule configured for the match.
Client Property Condition Prompts for the second factor by matching the requesting client against a set of expressions.

Attribute Enable Condition

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.

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.

Attribute Enable Condition

Configuration

The second factor to use when condition is true is statically configured on the action along with the attribute name to look for.

../../_images/mfa-enable-attribute-condition.png

Fig. 99 Configuration of the Attribute Enable Condition

Attribute ACR 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.

../../_images/mfa-acr-condition-overview.png

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.

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.

Configuration

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.

../../_images/mfa-attribute-acr-condition.png

Fig. 100 Configuration of the Attribute ACR Condition

Subject 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.

Configuration

An ordered list of regular expressions and what authenticator to run when a match is found.

../../_images/mfa-subject-condition.png

Fig. 101 Configuration of the Subject Condition

Client Property 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:

Condition Authenticator
client.properties.group === 'external' TOTP
client.properties.group === 'internal' SMS

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.

Client Object

The client object has the following members:

Key Type Description
id String The ID of the client.
name String The friendly name of the client.
properties Map A map of the client properties.
requires_consent Boolean true if the client is configured to require consent.
is_public Boolean true if the client is public.

Subject Check

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.

Important

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.