Page Comparison

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

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.

...

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.

General Configuration

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 is marked with an empty or null key value in the map.

Each transition rule is a mapping from the exit state (event) of a flow and the logic to run to decide the next flow to run. There are a couple of simple properties to define transitions to use after a "proceed" event (the usual success indicator), and a more advanced property to supply a full range of event/logic mappings.

If you need to support multiple workflows at the same time (e.g., if you wish to deploy special workflows to handle different profiles and functions provided by the IdP), you can supply a function in a bean called shibboleth.authn.MFA.TransitionMapStrategy to return the actual map of rules to use. Normally a single set is enough, since you can embed conditional logic in the rules, but this provides a separate axis of conditional logic you can use.

Defining Transitions

There are three approaches to defining transitions, 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:

1. Run the "authn/Flow1" flow.
2. If Step 1 succeeds, run the "authn/Flow2" flow.
3. If Step 2 succeeds, combine the results of the two flows into one.
4. 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:

...

Enabling Module (V4.1+)

For V4.1+, 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

General Configuration

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 is marked with an empty or null key value in the map.

Each transition rule is a mapping from the exit state (event) of a flow and the logic to run to decide the next flow to run. There are a couple of simple properties to define transitions to use after a "proceed" event (the usual success indicator), and a more advanced property to supply a full range of event/logic mappings.

If you need to support multiple workflows at the same time (e.g., if you wish to deploy special workflows to handle different profiles and functions provided by the IdP), you can supply a function in a bean called shibboleth.authn.MFA.TransitionMapStrategy to return the actual map of rules to use. Normally a single set is enough, since you can embed conditional logic in the rules, but this provides a separate axis of conditional logic you can use.

Defining Transitions

There are three approaches to defining transitions, 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:

1. Run the "authn/Flow1" flow.

2. If Step 1 succeeds, run the "authn/Flow2" flow.

3. If Step 2 succeeds, combine the results of the two flows into one.

4. 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).

...

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

1. Run the "authn/Flow1" flow.

2. If Step 1 succeeds and the result is sufficient to satisfy the request, resolve an attribute about the user identified by Step 1.

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

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

5. If successful, combine the results from the two flows into one.

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

...

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.

...

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

<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 calls a flow to display a view to select a method to run. -->
	<entry key="authn/Flow1">
		<bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="custom/methodChooser" />
	</entry>

	<!-- Third rule decides what to call based on event signaled by the view. -->
	<entry key="custom/methodChooser">
		<bean parent="shibboleth.authn.MFA.Transition">
			<property name="nextFlowStrategyMap">
				<map>
					<!-- Maps event to a flow -->
					<entry key="ChooseMethodA" value="authn/FlowA" />
					<entry key="ChooseMethodB" value="authn/FlowB" />

					<!-- Maps event to a scripted function bean reference-->
					<entry key="EventToHandle" value-ref="eventHandlerScript" />
				</map>
			</property>
		</bean>
	</entry>	

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

<!-- Event Handler Script -->
<bean id="eventHandlerScript" parent="shibboleth.ContextFunctions.Scripted" factory-method="inlineScript">
    <constructor-arg>
	    <value>
		    <![CDATA[
			...
		    ]]>
		</value>
    </constructor-arg>
</bean>

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

...

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.

...

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.

...

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.

...

There is an explicit property you can set on the login flow descriptor bean in authn/general-authn.xml (V4.0), or by defining a bean and setting a corresponding idp.authn.FlowMFA.reuseCondition property (V4.1+) 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/general-authn.xml

...
		<bean id="authn/MFA" parent="shibboleth.AuthenticationFlow"

				p:passiveAuthenticationSupported="true"

				p:forcedAuthenticationSupported="true"
				p:reuseCondition="false">

			...etc...

		</bean>
...

authn/authn.properties

...
idp.authn.MFA.reuseCondition = shibboleth.Conditions.FALSE
...

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

The beans defined in authn/mfa-authn-config.xml follow:

...

shibboleth.authn.MFA.TransitionMap

Map<String,MultiFactorAuthenticationTransition>

...

shibboleth.authn.MFA.TransitionMapStrategy

Function<ProfileRequestContext,Map<String,MultiFactorAuthenticationTransition>

...

shibboleth.authn.MFA.Transition

MultiFactorAuthenticationTransition

...

shibboleth.authn.MFA.validateLoginTransitions

Boolean

...

shibboleth.authn.MFA.resultMergingStrategy

Function<ProfileRequestContext,AuthenticationResult>

...

shibboleth.authn.MFA.resultCachingPredicate

Predicate<ProfileRequestContext>

...

Notes

It's been observed by early deployersto evaluate to decide on reuse, and you can attach that bean by name.

Reference

<list>
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol" />
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" />
    <bean parent="shibboleth.SAML2AuthnContextClassRef"
        c:classRef="urn:oasis:names:tc:SAML:2.0:ac:classes:Password" />
    <bean parent="shibboleth.SAML1AuthenticationMethod"
        c:method="urn:oasis:names:tc:SAML:1.0:am:password" />
</list>

idp.authn.MFA.supportedPrincipals = \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocol, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport, \
    saml2/urn:oasis:names:tc:SAML:2.0:ac:classes:Password, \
    saml1/urn:oasis:names:tc:SAML:1.0:am:password

<util:list id="shibboleth.AvailableAuthenticationFlows">
 
    <bean p:id="authn/MFA" parent="shibboleth.AuthenticationFlow"
            p:order="%{idp.authn.MFA.order:1000}"
            p:nonBrowserSupported="%{idp.authn.MFA.nonBrowserSupported:true}"
            p:passiveAuthenticationSupported="%{idp.authn.MFA.passiveAuthenticationSupported:true}"
            p:forcedAuthenticationSupported="%{idp.authn.MFA.forcedAuthenticationSupported:true}"
            p:proxyRestrictionsEnforced="%{idp.authn.MFA.proxyRestrictionsEnforced:%{idp.authn.enforceProxyRestrictions:true}}"
            p:proxyScopingEnforced="%{idp.authn.MFA.proxyScopingEnforced:false}"
            p:discoveryRequired="%{idp.authn.MFA.discoveryRequired:false}"
            p:lifetime="%{idp.authn.MFA.lifetime:%{idp.authn.defaultLifetime:PT1H}}"
            p:inactivityTimeout="%{idp.authn.MFA.inactivityTimeout:%{idp.authn.defaultTimeout:PT30M}}"
            p:reuseCondition-ref="#{'%{idp.authn.MFA.reuseCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:activationCondition-ref="#{'%{idp.authn.MFA.activationCondition:shibboleth.Conditions.TRUE}'.trim()}"
            p:subjectDecorator="#{getObject('%{idp.authn.MFA.subjectDecorator:}'.trim())}">
        <property name="supportedPrincipalsByString">
            <bean parent="shibboleth.CommaDelimStringArray"
                c:_0="#{'%{idp.authn.MFA.supportedPrincipals:}'.trim()}" />
        </property>
    </bean>
 
</util:list>

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.