The Shibboleth IdP V4 software has reached its End of Life and is no longer supported. This documentation is available for historical purposes only. See the IDP5 wiki space for current documentation on the supported version.
MultiFactorAuthnConfiguration
- Scott Cantor
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.
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 (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.MFAGeneral Configuration
Note that when you use the MFA flow, it's common that it will 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 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:
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
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.