Supporting the REFEDS MFA Profile (V5+)

This material is specific to IdP V5+ and is not necessarily compatible with older versions.

1 Background
2 Assumptions
3 Initial Setup
4 Adding REFEDS
5 Supporting Multiple Duo Policies

Background

The REFEDS MFA Profile is a convention for defining basic criteria needed to plausibly claim that one has applied multi-factor authentication to a subject and a standard SAML AuthnContext class reference value for communicating that between IdPs and SPs so that it's possible to leverage MFA on a wider scale than simple internally to an IdP organization.

Typically, MFA is something people apply today based on IdP-centric policy rules, whereas in the original SAML standard it was imagined that SPs would not have to rely on an IdP rule but simply ask for MFA when they needed it at runtime. This became a problem not only because of lack of software support outside of Shibboleth but also because there were no sensible values to use to communicate this. REFEDS as a community can't fix the former, but sought to address the latter by defining a value to use with a reasonably but not overly onerous bar for IdPs to meet in satisfying it.

Please note that this is not the same as, or related really at all to, the REFEDS Assurance Profile. Identity Assurance is distinct from, and expressed differently, than authentication quality.

It is difficult to document exactly how to "support" this because it is dependent on how one operates their IdP and what mechanisms are used for authentication but as a basic guide, this recipe assumes a very vanilla configuration and uses Password and DuoOIDC (i.e., the Duo Universal Prompt) authentication as the two factors involved. The examples should be readily generalizeable to other methods because the IdP treats all login methods more or less abstractly and with the same machinery.

Do NOT attempt to just cut and paste these examples; in most cases they will NOT work as is because they're excerpts of files and even beans that will contain other settings. They simply demonstrate the specific settings involved in this use case.

Also, this example is NOT suitable for use by anyone using third-party SAML IdP products to actually handle user authentication. That's a much different, and much more complex, problem that involves fairly advanced usage of the SAML proxying support in the IdP. That would require very faithful support of the SAML standard that is unlikely to be found in the commercial IdP space. In particularly, the IdP product would have to support requesting and signaling MFA via the SAML <AuthnContextClassRef> mechanism, or it may be impossible (or at least much more difficult) to pull off what this example is demonstrating for a Shibboleth-only deployment.

Assumptions

The example assumes that the IdP is using the Password and DuoOIDC flows together in a simple/standard way by means of the MFA flow that ties them together. The approach shown is usable to support both IdP-based and SP-based rules for applying the second (Duo) factor to a request.

The example further assumes that you want to define both an internal means of identifying and communicating MFA but also support the REFEDS signal value of "https://refeds.org/profile/mfa". The benefit of this approach is that it isolates internal use and separates the behavior of a REFEDS Profile deployment from any local policies or exceptions needed because of internal business decisions. For example, locally a decision to exempt certain users from a requirement to perform MFA through some kind of bypass mechanism would violate the REFEDS Profile requirements, so using a different string internally allows for that flexibility.

The example uses a made-up internal value which should be adjusted into a locally-defined/owned URI. The REFEDS value is of course the actual value needed.

Initial Setup

The example proceeds by establishing the configuration to support the internal value, which for example purposes is just "http://example.org/ac/classes/mfa". The REFEDS support will be added later below. For completeness, the example also includes support for expressing MFA as a SAML 1.1 AuthenticationMethod but this is unlikely to matter much at this point.

To begin with, the Password and DuoOIDC configurations must be established, and this is largely outside the scope of this example. Having done so, the MFA flow is then configured to tie the two factors together in a simple way that is designed to always apply the password factor and conditionally apply the Duo factor when and if it is necessary to do so. (The MFA "module" has to be enabled first, which is noted in the documentation, so we assume this is already done.)

This is virtually verbatim done via the distributed example that is installed with the software, but is repeated here for context:

    <util:map id="shibboleth.authn.MFA.TransitionMap">
        <!-- First rule runs the Password login flow. -->
        <entry key="">
            <bean parent="shibboleth.authn.MFA.Transition" p:nextFlow="authn/Password" />
        </entry>
        
        <!--
        Second rule runs a function if Password succeeds, to determine whether an additional
        factor is required.
        -->
        <entry key="authn/Password">
            <bean parent="shibboleth.authn.MFA.Transition" p:nextFlowStrategy-ref="checkSecondFactor" />
        </entry>
        
        <!-- An implicit final rule will return whatever the final flow returns. -->
    </util:map>

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

                // Check if second factor is necessary for request to be satisfied.
                authCtx = input.getSubcontext("net.shibboleth.idp.authn.context.AuthenticationContext");
                mfaCtx = authCtx.getSubcontext("net.shibboleth.idp.authn.context.MultiFactorAuthenticationContext");
                if (mfaCtx.isAcceptable()) {
                    nextFlow = null;
                }
                
                nextFlow;   // pass control to second factor or end with the first
            ]]>
            </value>
        </constructor-arg>
    </bean>

The additional setup below is the process by which you associate the "internal" SAML AuthnContext class reference value with your second-factor method (Duo in this case) so that it can act as a signal.

conf/authn/duo-oidc.properties

...

idp.authn.DuoOIDC.supportedPrincipals = \
    saml2/http://example.org/ac/classes/mfa, \
    saml1/http://example.org/ac/classes/mfa

...

conf/authn/authn.properties

...

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

...

Testing

Once this is in place, you can test the behavior (e.g., in development) by temporarily adjusting the default behavior of the IdP to require MFA for all requests by attaching the same local value to the DefaultRelyingParty configuration of the SAML 2.0 SSO profile:

conf/relying-party.xml

Aside from seeing MFA applied, you should also find that the resulting assertions carry an <AuthnContextClassRef> element matching the expected value.

Adding REFEDS

The final step is to simply extend what's already been done to include the REFEDS context class so that SPs that need it can request it. This is a straight addition to the principal sets in the earlier examples, and the original values are included for completeness. You could also add the value as a SAML 1.1 option in an obvious way but that isn't likely to matter or come into play given that SAML 1.1 SPs, if they exist, can't actually request anything.

conf/authn/duo-oidc.properties

conf/authn/authn.properties

Testing

Once the REFEDS value is in place, you can test that in the same way as earlier, just changing the trigger value:

conf/relying-party.xml

Supporting Multiple Duo Policies

As a final extention of this example, suppose that, having deployed separate context class values for REFEDS and local use, a decision is made to implement a Duo policy of some kind that would violate the REFEDS Profile. The only way to prevent that change from contaminating requests for the REFEDS Profile is to establish a second Duo integration for local use where that policy change is implemented. The original integration would be left alone.

The DuoOIDC flow documentation describes in general how to support multiple integrations. The point of this example is to demonstrate concretely how to use <AuthnContextClassRef> values in the form of custom Principals to make the determination as to which integration to use at runtime.

The core of this approach is that you want the DuoOIDC and MFA flows to support both the local and REFEDS context class values, which was done earlier, but you then need to further subdivide things by explicitly associating each Duo integration object with the specific context class Principals supported by that integration. In other words, the Duo flow as a whole supports both, but the actual integrations don’t. Then you need a scripted function that will properly select among the two based on whether they support the current request or not. This approach actually generalizes to more than just 2 possible context class values, so multiple local values could also be defined to represent different policies, but the example will stick to just two.

The example also makes use of additional custom properties to allow storage of the various keys outside the XML.

An assumption of this example is that the “local” integration as less strict in some sense than the REFEDS integration. That is, it assumes that a request for local MFA would be satisfied if the user had already performed REFEDS MFA. Because of that assumption, the appropriate configuration is for the “local” integration to support only the local Principal values, but the REFEDS integration to support both local and REFEDS Principal vales. If the local integration were actually more strict, such that a request for REFEDS MFA is satsified by local MFA but not the converse, then this would be reversed.

Finally, to make this all work, you need to prevent the Duo flow from automatically attaching all of the Principals the flow supports to the resulting Subject. This allows only the Principals supported by the integration that was actually used to be included, preventing an earlier local MFA result from being reused for REFEDS requests.

Just set the property idp.authn.DuoOIDC.addDefaultPrincipals to false in conf/authn/duo-oidc.properties