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:

Identity Provider 5