Introduction

Many cybersecurity experts agree that Multi-Factor Authentication (MFA) is the single most effective defense against password hacking. MFA enhances security by requiring two or more independent and distinct factors to authenticate a user (something you have, something you know, and something you are). The technology industry is moving quickly to Two-Factor Authentication (2FA) or MFA when accessing web-based applications and services.

CANARIE recently completed a proof-of-concept project with a small group of Canadian Access Federation (CAF) participants interested in enabling the Research and Education FEDerations (REFEDS) group MFA with their Federated Identity Management (FIM) Identity Provider (IdP).

If you have any questions, please contact us at: [email protected]

What is REFEDS?

The Research and Education Federations (REFEDS) group “represent the requirements of research and education in the ever-growing space of access and identity management, working with and influencing the direction of other organisations on behalf of our participants.”

The Research and Education Federations (REFEDS) group

Configuration Combinations Covered

This guide will describe configuration steps for various research and education (R&E) identity provider platforms using popular MFA technology from DUO Security or Microsoft Azure:

• Shibboleth with DUO MFA
• Shibboleth Proxy with Azure MFA
• ADFSToolkit with DUO MFA
• ADFSToolkit with Azure MFA

Who Should Read This Guide?

The configuration details are highly technical and are intended for identity and access management specialists who are:

• responsible for implementing and maintaining FIM at their institution
• interested in implementing MFA for their site

REFEDS MFA Overview

The REFEDS-MFA approach improves and simplifies the existing Security Assertion Markup Language Single Sign-On (SAML SSO) experience by using a common signal to trigger MFA. This way, the diverse MFA options in the field consolidate to one value for the variable “AuthenticationContextClass” included in the service provider’s authentication request. When a service provider includes the REFEDS-MFA profile in its request, the IdP is obligated to use a sign-on method that complies with a minimum MFA requirement of two or more independent and distinct factors for sign-on.

It is important to note that service providers may enforce MFA policy by including MFA in authentication requests, which means all IdPs must provide the proof of MFA in the authentication response before users are granted access. If an Identity Provider wishes to enforce MFA policy, they may do so regardless of whether the service provider requests MFA or not.

We strongly encourage reviewing the REFEDS MFA FAQ for more details.

An overview of the various SAML Authentication Contexts is provided below to help navigate the expected authentication experience and associated context. Sites may already have MFA partially in place on campus, but they may not be as strict as REFEDS-MFA. We encourage sites that want to be selective on where they apply MFA to adopt the model of using an AuthenticationContextClass that they control locally as illustrated (by the URL notation) below.

IDP System and Component Requirements

The guidance for enabling REFEDS MFA for identity providers requires a fully functional IdP installed with base configuration (i.e., can properly perform user ID and password login and resolve user attributes) before following one of the MFA configurations (with requisite component versions listed below).

Required Skillset

For Shibboleth IdP Installations

Configuration steps assume you are familiar with the Shibboleth IdP, software installation, and its layout.

Note that Shibboleth v4.1 and later use a new plugin configuration technique that are depicted throughout this guide.

For ADFSToolkit IdP Installations

The configuration steps assume familiarity with ADFS software installation and configuration, use of PowerShell, PowerShell Modules, and familiarity with Active Directory PowerShell commands.

Implementation

Shibboleth & DUO-OIDC

Implementing REFEDS-MFA for Shibboleth using DUO for MFA with the Shibboleth IdP is a good fit if you already have a DUO-based site.

IMPORTANT – All the following steps start with a Shibboleth IdP that can properly perform user ID and password login and resolve user attributes.

Step 1. Review and ensure you are ready for the DUO OIDC configuration.

This implementation uses the latest DUO features known as the DUO-OpenID Connect (OIDC) implementation. Sites using the older DUO iFrame approach should read the Breaking up with the iFrame blog post and migrate from the older iFrame before starting.

Step 2. Prepare the modules and dependencies for the IdP.

The Shibboleth Wiki details settings and techniques in a thorough Quick Step Guide. Specific tasks to enable DUO OIDC with REFEDS MFA are listed below:

Task: Download IdP configuration assistance tools

Clone CANARIE’s IdP widget library from GitHub or download and unzip it locally:

• Git clone
• Download zip

Task: Install the necessary plugins and libraries

Run idp-widgets/bin/prep-idp4mfa.sh

This will install the necessary DUO and OIDC common libraries into the IdP.

Step 3. Enable and activate your DUO configuration

Task: Activate your DUO configuration on the DUO site

Follow DUO’s implementation guidance to set up and prepare your DUO configuration.

Task: Set your DUO properties in the IdP in conf/aiuthn/duo-oidc.properties

In conf/authn/duo-oidc.properties adjust the following with your DUO details:

idp.duo.oidc.apiHost = hostname
idp.duo.oidc.clientId = clientid
idp.duo.oidc.redirectURL = https://<IDP-hostname>/idp/profile/Authn/Duo/2FA/duo-callback
idp.duo.oidc.secretKey = key 

Step 4. Configure MFA settings in the IdP

Task: Adjust idp.properties to have only the MFA flow

In idp.properties ensure the MFA flow is enabled:

idp.authn.flows=MFA

The Shibboleth Wiki MFA documentation calls this out (paraphrased):

When you use the MFA flow, it’s common that it will be the only flow enabled via the idp.authn.flows property. Any MFA-directed flows you run via rules and scripts should not be enabled themselves because it may cause the IdP to run them in ways that are likely to subvert your intent.

Task: Update MFA flow in mfa-authn-config.xml

Below is an example flow defined in the conf/authn/mfa-authn-config.xml file. If this file is missing, you have not yet enabled the “idp.authn.MFA” module. (See reference)

<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. Currently just returns the DuoOIDC flow -->
    <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>

Task: Update conf/authn/authn.properties to support REFEDS MFA

Update authn.properties file so that it contains the MFA supported Principals for REFEDS MFA (highlighted in green). These are the strings that match the AuthenticationContext that the IdP should handle.

…

idp.authn.Duo.supportedPrincipals = \
    saml2/https://refeds.org/profile/mfa, \
    saml2/http://example.org/ac/classes/mfa, \
    saml1/http://example.org/ac/classes/mfa
 
...
 
idp.authn.MFA.supportedPrincipals = \
    saml2/https://refeds.org/profile/mfa, \
    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

Task: Restart the IdP and test

Testing the IdP requires a test service provider that starts its request with the REFEDS MFA AuthenticationContext. After restarting your IdP visit the CAF test site at https://validator.caftest.canarie.ca and select the MFA sign-on to exercise and validate your MFA configuration.

Note that we need to have your metadata already circulating for this to work. If you want to implement your own test service provider, please see the “Shibboleth SP MFA Installation” section below.

After signing on, examine the SP’s session status here: http://validator.cafteste.canarie.ca/Shibboleth.sso/Session

Shibboleth & Azure MFA

Implementing REFEDS-MFA for Shibboleth using Azure MFA requires the Shibboleth IdP to be configured as a SAML proxy. This means that the IdP passes the request back to Azure AD with a specific AuthenticationContext to trigger the MFA process. When it returns, it transforms it back into the appropriate form.

Note that if the user in Azure AD has no MFA capabilities, they can’t sign in until they enroll and activate the MFA features of their account.

Details on this are found on the Shibboleth Wiki Knowledgebase.

Of specific interest is Proxy Task 6 where the transformation of the request is performed:

Proxy Task 6 – Handling REFEDS AuthnContext Requests

Azure does not currently have a documented way to influence the behaviour of the AuthnContext in their SAML assertions. However, Shibboleth provides the means to translate proxy requests and responses via authn/authn-comparison.xml. The example below handles REFEDS MFA requests:

<util:map id="shibboleth.PrincipalProxyRequestMappings">
    <entry>
         <key>
            <bean parent="shibboleth.SAML2AuthnContextClassRef"
                  c:classRef="https://refeds.org/profile/mfa" />
        </key>
        <list>
            <bean parent="shibboleth.SAML2AuthnContextClassRef"
                  c:classRef="http://schemas.microsoft.com/claims/multipleauthn" />
        </list>
    </entry>
</util:map>
<util:map id="shibboleth.PrincipalProxyResponseMappings">
    <entry>
         <key>
            <bean parent="shibboleth.SAML2AuthnContextClassRef"
                          c:classRef="http://schemas.microsoft.com/claims/multipleauthn" />
        </key>
        <list>
            <bean parent="shibboleth.SAML2AuthnContextClassRef"
                          c:classRef="https://refeds.org/profile/mfa" />
        </list>
    </entry>
</util:map>

To test your configuration, visit the CAF Test Site  and select the MFA sign-on to exercise and validate your MFA configuration.

ADFS/ADFSToolkit

 To enable REFDS-MFA support for ADFS:

• Work in the latest version of ADFSToolkit.
• Have the latest version of your MFA technology in place and independently operating as expected.
• Enable the ADFS Paginated theme.
• Review the installation and configuration of REFEDS MFA for ADFSToolkit guidance.
• Plan how you will distribute MFA capability and features to your users.

Installing REFEDS-MFA capability is one element of the overall approach to provide MFA to your users. This guide focuses on the technical infrastructure required to implement MFA. However, we do not discuss the logistics for assisting or training your users on how to enroll, use, and reset an MFA token device for account access.

Follow the ADFSToolkit MFA Installation and Configuration instructions here, so that your ADFS instance will have a new DLL plugin added to support the REFEDS-MFA. You will also have a few PowerShell cmdlets to ease installation and configuration.

Once the REFEDS-MFA support is successfully installed, all the Relying Parties (RPs) in ADFS that ADFSToolkit oversees will be recalculated to ensure proper operation with your chosen MFA technology (e.g., DUO-OICD, Azure MFA). 

To function properly, ADFSToolkit’s use of the ADFS extensions via the DLL requires the Paginated theme to be installed. If you want to use REFEDS-MFA you must use either the stock Microsoft Paginated theme or one that is tailored to your specific needs.

ADFS/ADFS Toolkit & DUO-OIDC

To implement REFEDS-MFA for ADFS/ADFSToolkit and enable DUO-OIDC integration, review and complete the configuration from DUO.

Note that if you are using sites with the older DUO iFrame approach, you should read the Breaking up with the iFrame blog post and migrate from the older iFrame before starting.

Once you have DUO’s installation complete, we recommend you independently test and verify it against a Relying Party you maintain or use Microsoft’s Test RP, Claims X-Ray. Use the SAML-P verification process that allows you to quickly test your sign-in experience.

ADFS/ADFS Toolkit & Azure MFA

Implementing Azure MFA with ADFS requires that you:

• synchronize your Active Directory with your Azure AD tenant.
• configure the appropriate MFA settings in your tenant.

We recommend you review details about the Azure AD MFA along with the REFEDS MFA FAQ to confirm that your desired behaviours or patterns of access are supported. 

SMS is no longer considered a safe or secure additional factor as it can easily be compromised or intercepted and is thus inappropriate for MFA use. Although it is still offered as an option, SMS as a factor is strongly discouraged.

Microsoft provides detailed steps on how to join ADFS to Azure AD MFA service. We encourage implementing using test systems with a test user first, so that you can experience the full configuration without disrupting users in your production environment.  

For Shibboleth SP MFA Installation

For service providers using Shibboleth SP, you can read the reference documents below on how to properly configure REFEDS MFA (Authentication Context) to ensure MFA access to your application.

If you have any questions, please contact us at: [email protected]