Important

This is a quick setup guide for the Duo OIDC 2FA Auth API plugin. Please see DuoOIDCAuthnConfiguration for more detailed information including advanced configuration options.

Pre-requisites

Installation of the OIDCCommon plugin

Typically this can be achieved as follows;

$ /opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.oidc.common

or

C:>\opt\shibboleth-idp\bin\plugin.bat -I

What we will install and configure

Installation of the DuoOIDC plugin.
1. Using the recommended Duo Client.
Configuring a basic Duo integration.
Configuring a basic MFA flow.
Enable MFA flow

1. Installation of the DuoOIDC plugin

Please check DuoOIDCAuthnConfiguration for links to the latest version.

Plugin Install

$ /opt/shibboleth-idp/bin/plugin.sh -I net.shibboleth.idp.plugin.authn.duo.nimbus

or

C:>\opt\shibboleth-idp\bin\plugin.bat -I net.shibboleth.idp.plugin.authn.duo.nimbus

2. Configuring a Duo Integration

Open the conf/authn/duo-oidc.properties file. Change the following with details of your Duo protected application:

Duo Integration Properties

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

3. Configuring a basic MFA flow

First, ensure the MFA and Password modules are enabled. Then, open the conf/authn/mfa-authn-config.xml file and add a basic MFA flow which includes Username and Password as a first factor. You must ensure the Password flow is properly configured.

Basic MFA Setup

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

4. Enable MFA flow

We need to ensure that MFA is called, so open conf/authn/auth.properties file and set idp.authn.flows accordingly

idp.authn.flows = MFA

DuoOIDCAuthnConfiguration-QuickSetup