MultiFactorAuthnConfiguration

Current File(s): conf/authn/mfa-authn-config.xml, conf/authn/authn.properties
Format: Native Spring, Properties

1 Overview
2 Enabling Module
3 General Configuration
4 Defining Transitions
- 4.1 Directly Selecting Flows
- 4.2 Programmatically Selecting Flows
- 4.3 Full Control Over Transitions
- 4.4 Signaling Completion
- 4.5 Custom Events
5 Merging Results
6 Running Login Flows and Reusing Results
7 Reference
8 Notes

Overview

The authn/MFA login flow is a special "composite" mechanism that provides a scriptable (or programmable) way of combining other login flows to produce simple or complex sequences of login challenges that combine to provide stronger or more flexible authentication options than individual methods can provide on their own.

It simplifies the development of new login methods by avoiding the need to include complicated business logic to control how methods are combined for specific users, services, networks, times of day, etc.

By itself, the MFA flow is just an orchestration tool and doesn't itself perform any specific kinds of authentication, instead relying on existing login methods to do its work, together with rules you must provide to control behavior. It requires that you plan out what you need to do first, and then implement that plan using Java code or Java Scripting to supply the business logic.

Enabling Module

Configuring and using this feature requires that you first enable the "idp.authn.MFA" module if it isn't already enabled. Systems upgraded from older releases generally come pre-enabled due to the prior state of the configuration tree.

(Windows)
C:\opt\shibboleth-idp> bin\module.bat -t idp.authn.MFA || bin\module.bat -e idp.authn.MFA
 
(Other)
$ bin/module.sh -t idp.authn.MFA || bin/module.sh -e idp.authn.MFA

In addition, most uses of this module tend to rely on the use of Javascript, so you will likely have to select and install one of our scripting plugins for that purpose due to Java’s removal of Javascript support.

General Configuration

Most of the flow configuration is in authn/mfa-authn-config.xml but some generic settings applicable to all login flows are in authn/authn.properties.

Note that when you use the MFA flow, it's common that it should be the only flow enabled via the idp.authn.flows property. In particular, any flows you direct the MFA flow to run via rules and scripts should not be enabled themselves because to do so may cause the IdP to run them itself in ways that are likely to subvert your intent.

Another note which is repeated below, regarding the overall method selection process: at the top level, the IdP won't run the MFA login flow at all if its supportedPrincipals setting does not satisfy the request. That is, you generally will need to advertise support for all possible custom principals represented by the various factors the MFA flow may produce results for in order to convince the IdP to run it.

As an example, if your MFA processing rules allow for certificate authentication, then you will need to ensure the MFA flow includes appropriate supported principals reflecting use of certificates, or the IdP won't know it can run the MFA flow for requests for that type of authentication.

A bean called shibboleth.authn.MFA.TransitionMap contains the map of rules to run to control the transition between flows and determine when to complete work. This is a map whose keys are the flows to "exit" from, and whose values are a bean of the class type net.shibboleth.idp.authn.MultiFactorAuthenticationTransition (a parent bean called shibboleth.authn.MFA.Transition is provided). The first rule to run is denoted by an empty or null key value in the map.

Each of these transition rules is itself a mapping from the exit state (event) of a flow to a (possibly constant) function to run to decide the next flow to run. There are a couple of simple ways to define transitions to use after a "proceed" event (the usual success indicator), and a more advanced way to supply a full range of event/logic mappings.

This transition class can be configured via three different properties to supply the function(s) to use to compute the next flow to run or to complete the process by returning a null or the “proceed” signal:

nextFlow – this installs a constant function that returns a fixed flow ID to run, essentially a shortcut for simple rules
nextFlowStrategy – this installs a function to run that returns the next flow to run
nextFlowStrategyMap – the most general, this installs a map between the events signalled by the previous flow and the flows to run in response to those events (either literally as a String or indirected even further as a function to run

In each case, the result of the logic executed is either a flow ID to run, null, or the explicit value “proceed”. The latter two cases signal the MFA flow to compete its work “successfully” by merging all the results it has accumulated into a final outcome (discussed later). The difference between null and “proceed” is that “proceed” is also a signal that any previous event being tracked should be cleared.

Defining Transitions

The three techniques for defining transitions via the three properties discussed above are outlined below, with examples.

Directly Selecting Flows

The simplest type of transition rule just provides a specific subflow to run if the previous step (if any) was successful. This is specified with the nextFlow property of a transition bean. Note that this can invoke any subflow, not just login flows, though that is the most common case. You could build your own subflows to display views to collect user input, etc. and invoke them using the same mechanism.

Consider a simple example that implements this sequence:

Run the "authn/Flow1" flow.
If Step 1 succeeds, run the "authn/Flow2" flow.
If Step 2 succeeds, combine the results of the two flows into one.
If either Step 1 or 2 fails, return that failure as the MFA flow result.

This simple example doesn't require any logic or scripting:

Simple sequence of factors Flow1 and Flow2

<util:map id="shibboleth.authn.MFA.TransitionMap">
	<!-- Run authn/Flow1 first. -->
	<entry key="">
		<bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Flow1" />
	</entry>

	<!-- If that returns "proceed", run authn/Flow2 next. -->
	<entry key="authn/Flow1">
		<bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Flow2" />
	</entry>
        
	<!-- An implicit final rule will return whatever the second flow returns. -->
</util:map>

The "combine the results" behavior in step 3 above actually comes from a built-in bean that you can override for more customized behavior. A bean named shibboleth.authn.MFA.resultMergingStrategy will be used to supply a function to run to merge together all of the authentication results produced by an entire sequence of steps in a customized way (this is discussed in more detail below).

Programmatically Selecting Flows

A more complex transition rule can run a function (which can be in Java, a script, or a Spring Expression) to return a flow to run if the previous step (if any) was successful, or it can return null to signal that processing should stop. This is specified with the nextFlowStrategy property of a transition bean.

This relatively complex example relies on a single script that does a number of interesting things to achieve the following sequence:

Run the "authn/Flow1" flow.
If Step 1 succeeds and the result is sufficient to satisfy the request, resolve an attribute about the user identified by Step 1.
If the result from Step 1 is sufficient AND the attribute resolved indicates that a user may use that method alone, then finish with the result from Step 1.
If the result from Step 1 is not sufficient OR the attribute resolved indicates that an additional factor is required, run the "authn/Flow2" flow.
If successful, combine the results from the two flows into one.
If either method fails, return that failure as the MFA flow result.

Conditional use of two factors, Flow1 and Flow2

<util:map id="shibboleth.authn.MFA.TransitionMap">
	<!-- Run authn/Flow1 first. -->
	<entry key="">
		<bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Flow1" />
	</entry>

	<!--
	Second rule runs a function if authn/Flow1 succeeds, to determine whether an additional
	factor is required.
	-->
	<entry key="authn/Flow1">
		<bean parent="shibboleth.authn.MFA.Transition" p:nextFlowStrategy-ref="checkSecondFactor" />
	</entry>

	<!-- An implicit final rule will return whatever the second flow returns. -->
</util:map>

<!-- Example script to see if second factor is required. -->
<bean id="checkSecondFactor" parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript"
		p:customObject-ref="shibboleth.AttributeResolverService">
	<constructor-arg>
		<value>
        <![CDATA[
            nextFlow = "authn/Flow2";

            // Go straight to second factor if we have to, or set up for an attribute lookup first.
            authCtx = input.getSubcontext("net.shibboleth.idp.authn.context.AuthenticationContext");
            mfaCtx = authCtx.getSubcontext("net.shibboleth.idp.authn.context.MultiFactorAuthenticationContext");
            if (mfaCtx.isAcceptable()) {
                // Attribute check is required to decide if first factor alone is enough.
                resCtx = input.getSubcontext(
                    "net.shibboleth.idp.attribute.resolver.context.AttributeResolutionContext", true);
                
				// Look up the username
                usernameLookupStrategyClass = Java.type("net.shibboleth.idp.session.context.navigate.CanonicalUsernameLookupStrategy");
                usernameLookupStrategy = new usernameLookupStrategyClass();
                resCtx.setPrincipal(usernameLookupStrategy.apply(input));


				// resolve the attribute to determine if a first factor is sufficient
                resCtx.getRequestedIdPAttributeNames().add("allowedLoginMethods");
                resCtx.resolveAttributes(custom);
                
                // Check for an attribute value that authorizes use of first factor.
                attribute = resCtx.getResolvedIdPAttributes().get("allowedLoginMethods");
                valueType =  Java.type("net.shibboleth.idp.attribute.StringAttributeValue");
                if (attribute != null && attribute.getValues().contains(new valueType("Flow1"))) {
                    nextFlow = null;
                }
                
                input.removeSubcontext(resCtx);   // cleanup
            }
            
            nextFlow;   // pass control to second factor or end with the first
        ]]>
	</value>
	</constructor-arg>
</bean>

There's a fair amount going in on the script, but it's mostly just navigating and populating contexts into the tree, and the whole middle section is doing the attribute lookup and check.

If you study that sequence, you will find that it represents the general outline of a typical "opt-in" strategy that is based on the user, and is also optimized to avoid extra work if specific requests require the second factor and addresses the failure scenario in which it's not possible to obtain the opt-in attribute (it fails in the direction of requiring the second factor).

Hopefully you can see how to adapt it for a similar scenario involving your particular strategy. Obviously the attribute name, values, and the specific flows involved will be local.

This is still a relative simple strategy in that it is driven only by successful results at each step, with errors left to fall through back into the IdP.

Full Control Over Transitions

The final tier of complexity is one that provides total control over transitions based on specific Spring WebFlow events that occur. That is, you can run scripts or signal flows to run in response to specific error events from previous steps, or build a subflow that deliberately signals a number of different events as a simple way to pass input from a user (via a view) back into the system to decide what to do. This should make building selection screens for choosing login methods fairly simple.

For full control, you must build a map bean and set it as the value of the nextFlowStrategyMap property of a transition bean. The keys to the map are the events to "catch", and the values of the map can either be a simple String (a subflow to run) or a Function<ProfileRequestContext,String> to run to return the flow to run.

Another feature is the ability to handle all events not otherwise specified (a wildcard). This is signified by a map key of "*" (an asterisk).

As an example, if you built a view-centric flow that signaled events indicating the type of authentication to perform, it might look something like the following:

Example with a method selection UI

The example above is geared around using a dedicated custom webflow to offer a selection UI, so such a flow controls its own rules for what events it can signal. If you wanted to, for example, stick a button or link on the login form used by the Password login flow and signal that back to the MFA logic as a custom event, you will need to modify conf/authn/authn-events-flow.xml (see the general discussion under Custom Events).

Signaling Completion

As shown in one of the examples above, a transition rule that either doesn't exist, doesn't handle a particular event, or returns an explicit null, is a signal to the MFA flow "proper" to finish work. At that point, the event is examined and if anything but "proceed" is signaled, that event becomes the final result of the MFA login flow and control passes back to the IdP. A basic example of this would be a call to a login flow that returned "InvalidPassword" after a number of failed attempts.

On the other hand, if "proceed" is the final event, then the MFA flow assumes success and performs a "merge" as described in the following section.

Custom Events

As with the “master” Authentication feature, custom events are supported (either internally to the MFA logic, or exposed externally as the “result” of the MFA flow’s use, generally to signal specific errors. For a custom event to work, some of the requirements are the same as in the general case while other specific requirements apply to the MFA flow because of how it manages event transitions.

Firstly, understand that the scripting rules in the MFA flow are designed to support running specific steps based on events, but they don’t have the ability to signal them. That is, the transition rules return flows ro tun, not events to signal, because the system has no way to tell the difference. Signalling events is programmatic, done via a setter method on the MultiFactorAuthenticationContext object in the request tree, specifically the setEvent method, which takes a String, the event to signal. Your scripting rules can signal an event by calling that method.

You must also define the event to the system by editing conf/authn/authn-events-flow.xml. There are two steps needed: adding an <end-state> for the event and adding a <transition> rule to authorize the event as a signal to cause the flow to terminate with that state. The file includes commented examples, and a sample is shown below that authorizes "MyCustomEvent" to be surfaced:

Authorizing custom login flow events in conf/authn/authn-events-flow.xml

Finally, you complete the process as above under Signaling Completion, by returning a null from your transition rule/script. If done correctly, the MFA flow will terminate with that event, and depending on the rest of the configuration, authentication overall will do the same.

Merging Results

The IdP expects/requires a login flow to produce a single AuthenticationResult when it finishes work successfully. To avoid a total redesign, the MFA flow is built to maintain this constraint by combining the individual results it may accumulate in the course of executing into one final result. It does this using a default function that can be overridden by defining a bean named shibboleth.authn.MFA.resultMergingStrategy of type Function<ProfileRequestContext,AuthenticationResult> (i.e., a function that returns the result to use).

It is hoped that the default behavior will be sufficient for most people, which is to perform a true merge of all of the Principals, and public and private Credentials contained in the individual Subjects across all of the active results contained in the MultiFactorAuthenticationContext that tracks the overall state of the request. In addition, to enable the SSO behavior described below, the default function actually wraps the individual results into a special custom Principal type that allows the MFA login flow to actually recover the individual results that it obtained earlier and use them to avoid re-prompting a user with factors that have already been performed, just as the IdP itself does.

Note that if you wish to replace this function, you will likely have to look at, and possibly replicate some of, the default behavior the system supplies to do so, but you do have the ability to do anything you like in producing a final result.

Running Login Flows and Reusing Results

If you have followed along this far, you probably should be figuring out that in a lot of respects, this login flow actually replaces the selection behavior that was baked into the IdP itself in prior versions. That behavior is still there, but once the IdP runs this flow, there's sort of an "algorithm within the algorithm" running to decide what flows to run.

To avoid creating a lot of disconnect with existing behavior, there are certain things that this flow does to maintain existing expectations.

Basic Flow Validation

By default, the MFA flow checks some of the basic parameters of a request and the ability of a login flow to handle them, before running it. That is, it checks things like forced authentication, passive authentication, and non-browser support, before it actually attempts a login flow, even if you signal that it should run one. This is mostly to keep certain kinds of scenarios working automatically without having to be handled in everybody's scripts and rules.

If you want to turn off that behavior, you can set the idp.authn.MFA.validateLoginTransitions property to false (V4.1+)

One thing it doesn't do is apply any activation condition you've attached to the subordinate login flow before running that flow. If you want to conditionally run a flow, that's the point of the MFA transition rule logic so you're meant to apply those conditions yourself if you want them. This provides more flexibility since you get to control when the condition applies, which allows, for example, different conditions to attach to the same login method depending on the situation. It's all the same in the end, it's just where the logic runs.

Request Sufficiency

One thing that is normally done by the IdP that is not done in the MFA flow is to check whether individual login flows are compatible with the authentication requirements of a request (see also AuthenticationFlowSelection). Often MFA scenarios require more customized decision making (e.g., forcing use of a method because of the user's identity, or preventing a method from running for some reason), and so you have more latitude in this area. But you need to bear in mind that at the end of the process, the result you produce had still better satisfy the request or the IdP will reject it. For example, if a service requests strong authentication in some way, and you short-circuit that by returning the result of password authentication and you accurately communicate that, that is likely to be rejected by the IdP and fail the request. You can lie of course, with sufficient cleverness, but the IdP isn't going to lie for you.

Repeating the note at the top of this page: at the top level, the IdP won't run the MFA login flow at all if its supportedPrincipals collection does not satisfy the request. That is, you generally will need to advertise support for all possible custom principals represented by the various factors the MFA flow may produce results for in order to convince the IdP to run it. As an example, if your MFA processing rules allow for certificate authentication, then you will need to ensure the MFA flow descriptor includes appropriate supported principals reflecting use of certificates, or the IdP won't know it can run the MFA flow for requests for that type of authentication.

Single Sign-On / Reuse By the MFA Flow

Like the IdP "proper", the MFA flow has a feature to reuse the results of the login flows it runs by pulling them out of a previous session. This is a little subtle: this does not compose with uses of login flows outside of the MFA flow. That is, if you have the IdP run the Password flow directly, that result is not recognized by the MFA flow, but if the MFA flow runs the Password flow, then the MFA flow will recognize it.

Unless a request includes forced re-authentication, any active/previous results produced and tracked by the MFA flow will be reused under these conditions:

the login flow is known to the system (i.e., it hasn't been removed with no descriptor bean left in place)
the result remains within the lifetime of the login flow, per policy

You will note this does not include a check for whether the result is specifically applicable to the request's requirements, because it assumes you are in control of that decision if you choose to run the flow.

Note that one feature the MFA flow does not have is individual timeouts. For various reasons, it was not practical to maintain an activity timeout on the individual results within the MFA flow, and so that check is not done. Using a shorter lifetime generally will compensate for that.

On the other hand, the overall MFA result that contains all of the individual results does have the normal lifetime/timeout policy the IdP supports. You can still time out any memory of any of the results, just not at a fine-grained level.

Also be aware that any given login flow can supply only a single result at a time to the overall merged result, and any result from a flow will overwrite a previous result.

Reuse of the Entire authn/MFA Flow Result (When Is a MFA Next Flow Strategy Executed?)

As with any other login flow, if the IdP determines that an active MFA flow result with a particular principal satisfies a request it will reuse the entire MFA result with that principal. As such the IdP will not rerun the authn/MFA flow and any logic in a next flow strategy in the transition map will not have a chance to execute a second time for that user.

The IdP may, however, be configured so that the IdP runs the MFA flow and executes the next flow strategy logic even if the result would normally satisfy the request. You can define a bean and set a corresponding idp.authn.MFA.reuseCondition property that attaches a second kind of condition logic to the login flows called a "reuse condition". Think of it as a "SSO or not?" flag on each login method that allows you to customize when the system will reuse a previously built result or re-run the flow. This is possible with any login flow, but it's of particular value with the MFA flow since it generally contains logic that may need to run to determine whether SSO should happen.

You can split these concerns any way you prefer, but if you can include at least some of your logic in the reuse condition rather than the MFA logic itself, that can improve efficiency. But in the simplest case, if you want the MFA rules to run on every request no matter what:

authn/authn.properties

That simply says "never reuse results". Bear in mind this is referring to the MFA flow itself, and not the individual "sub factors" that it uses internally to build its results, so individual factors may have results reused when the MFA logic actually runs them, which is generally what is desired.

For more advanced cases or to improve efficiency, a bean can be defined for a script or Java logic that defines the condition to evaluate to decide on reuse, and you can attach that bean by name.

Reference

Beans defined in authn/mfa-authn-config.xml follow:

Bean ID / Type	Default	Description

Bean ID / Type	Default	Description
shibboleth.authn.MFA.TransitionMap Map<String,MultiFactorAuthenticationTransition>		Static ruleset containing the starting point for MFA execution and the rules to use to decide how to do work
shibboleth.authn.MFA.TransitionMapStrategy Function<ProfileRequestContext,Map<String,MultiFactorAuthenticationTransition>		Optional function bean to return the ruleset to use instead of using a static ruleset
shibboleth.authn.MFA.Transition MultiFactorAuthenticationTransition		Parent bean for defining transition rules in the values of the previous bean's map entries
shibboleth.authn.MFA.resultMergingStrategy Function<ProfileRequestContext,AuthenticationResult>	described above	Function to run to produce final merged result of MFA login flow during successful completion
shibboleth.authn.MFA.resultCachingPredicate Predicate<ProfileRequestContext>		An optional bean that can be defined to control whether to preserve the authentication result in an IdP session

Properties specific to this flow defined in authn/authn.properties are:

Name	Default	Description

Name	Default	Description
idp.authn.MFA.validateLoginTransitions	true	Whether login flows should only be run with regard for forceAuthn/isPassive/nonBrowser (and similar) conditions
idp.authn.MFA.useLatestTimestamp	false	Whether the result’s “time of authentication” should reflect the earliest component result or the latest

The general properties configuring this flow via authn/authn.properties are:

Name	Default	Description

Name	Default	Description
idp.authn.MFA.order	1000	Flow priority relative to other enabled login flows (lower is "higher" in priority)
idp.authn.MFA.nonBrowserSupported	true	Whether the flow should handle non-browser request profiles (e.g., ECP)
idp.authn.MFA.passiveAuthenticationSupported	true	Whether the flow allows for passive authentication
idp.authn.MFA.forcedAuthenticationSupported	true	Whether the flow supports forced authentication
idp.authn.MFA.proxyRestrictionsEnforced	%{idp.authn.enforceProxyRestrictions:true}	Whether the flow enforces upstream IdP-imposed restrictions on proxying
idp.authn.MFA.proxyScopingEnforced	false	Whether the flow considers itself to be proxying, and therefore enforces SP-signaled restrictions on proxying
idp.authn.MFA.discoveryRequired	false	Whether to invoke IdP-discovery prior to running flow
idp.authn.MFA.lifetime	%{idp.authn.defaultLifetime:PT1H}	Lifetime of results produced by this flow
idp.authn.MFA.inactivityTimeout	%{idp.authn.defaultTimeout:PT30M}	Inactivity timeout of results produced by this flow
idp.authn.MFA.reuseCondition	shibboleth.Conditions.TRUE	Bean ID of Predicate<ProfileRequestContext> controlling result reuse for SSO
idp.authn.MFA.activationCondition	shibboleth.Conditions.TRUE	Bean ID of Predicate<ProfileRequestContext> determining whether flow is usable for request
idp.authn.MFA.subjectDecorator		Bean ID of BiConsumer<ProfileRequestContext,Subject> for subject customization
idp.authn.MFA.supportedPrincipals	(see below)	Comma-delimited list of protocol-specific Principal strings associated with flow
idp.authn.MFA.addDefaultPrincipals	false	Whether to auto-attach the preceding set of Principal objects to each Subject produced by this flow

As a generic flow, the supportedPrincipals property defaults to the following XML:

In property form, this is expressed as:

This default is not intended to be applicable to most systems, but matches the behavior of the flow's default/example configuration which accounts for both the IPAddress and Password flows being combined.

Notes

It's been observed, accurately, that the data required to track the use of this feature in the session cache is on the order of 2-3 times as large as just a "simple" authentication result. While it is believed that this remains acceptable with the use of cookies, and certainly with HTML Storage, some storage service implementations such as that for Memcached rely on a less reliable persistence model that may prematurely evict data, so such options may not be a good fit with this feature.

Identity Provider 5