Configure a Service Provider for Step-up Two-Factor Authentication

Last updated: July 9, 2024
Audience: IT Staff / Technical

This guide shows how to configure a Shibboleth Service Provider (SP) to “step up” from password to two-factor authentication (Duo) for an existing session. This is useful if you protect your resources with a password, but need stronger authentication for certain resources.

Prerequisites

This guide assumes you have read and understood basic two-factor authentication.

Note

Before configuring 2FA on a service provider, please ensure all users meet the current eligibility requirements as outlined in the 2FA FAQ.

Introduction

Normally, once Shibboleth has established a valid session it will not reevaluate session initiation requests. This means if a user accesses a “one-factor” (password) protected resource, and then decides to access a two-factor protected resource, Shibboleth must initiate a new session.  The second factor cannot be “added” to the existing session. To force a session initiation you can:

  1. Clear any existing session and then initiate a two-factor login.  You can do this by:
    • Initiating a logout–not very user-friendly
    • Clearing Shibboleth’s cookies–does not cleanup a session as well as logout
  2. Implement two-factor step-up as a separate application
    • Configure an application override in shibboleth2.xml

This document describes the application override option.

Procedure

A service provider MUST be configured both to request 2FA and to verify that 2FA was used during sign-in. Failure to follow these configuration directions completely may result in the ability to bypass the use of 2FA when signing in to an incorrectly configured application.

1. Define the content that requires 2-factor step-up

1.1. Define the content that requires two-factor step-up by using Path statements within a RequestMap definition. The RequestMapper section is sometimes missing from the default shibboleth2.xml. If so, add it just before the ApplicationDefaults section.

1.2. On an Apache system in shibboleth2.xml:

<RequestMapper type="Native">
    <RequestMap>
       <Host name="your-host">
           <Path name="stepup" applicationId="stepup2f"
                 authnContextClassRef="https://refeds.org/profile/mfa" />
       </Host>
   </RequestMap>
</RequestMapper>

1.3. On an IIS system:

On IIS both defining the content which requires step-up and the verification process to ensure it was used during sign-in are configured within the <RequestMapper> in shibboleth2.xml.

<RequestMapper type="Native">
    <RequestMap>
       <Host name="your-host">
           <Path name="stepup" applicationId="stepup2f" authType="shibboleth" requireSession="true"
                 authnContextClassRef="https://refeds.org/profile/mfa">
                <AccessControl>
                    <Rule require="authnContextClassRef">https://refeds.org/profile/mfa</Rule>
                </AccessControl>
            </Path>
       </Host>
   </RequestMap>
</RequestMapper>

For more information on defining paths and requirements when defining multiple paths that are partly overlapping, see the Shibboleth project’s NativeSPRequestMapHowTo.

2. Configure an application override

2.1. In your shibboleth2.xml find the example ApplicationOverride at the end of the ApplicationDefaults section.

2.2. Add an override element that looks like:

<!-- Step-up two-factor at UW -->
<ApplicationOverride id="stepup2f">
    <Sessions handlerURL="/stepup/Shibboleth.sso" />
</ApplicationOverride>

Some Things to Keep in Mind

  • The ApplicationOverride id, ‘stepup2f’ in this example, can be named anything you like, but each Application Override you define must have a unique name and it must match the name provided in the corresponding Path statement defined in step 1.
  • The handlerURL should be “/” + your path from step 1 + “Shibboleth.sso”
  • Although not shown in the example <Sessions> element above, any attributes from your ApplicationDefaults <Session> element that you also want applied to the ApplicationOverride must be copied into the <Sessions> element at the ApplicationOverride level.
  • As described here, the Service Provider will accept two-factor logins from other UW sites that have been made in the previous 12 hours. If instead you wish to always enforce two-factor login for every visitor to your site, you should add forceAuth="true" to your session initiator. See Configure a Service Provider to Force Re-Authentication for more information.

3. Requesting step-up to two-factor and verifying two-factor session

Your application simply needs to request the application id.

3.1. For an Apache directory you might use the following Apache directives:

Apache 2.4

To configure Apache 2.4 to require the authentication was completed with 2FA a combination of Shibboleth specific and standard Apache access control directive can be used. The below example will restrict access to any users who have used 2FA to sign in with their UW NetID.

AuthType shibboleth
ShibRequestSetting requireSession true
ShibRequestSetting applicationId stepup2f
 
<RequireAll>
    Require authnContextClassRef https://refeds.org/profile/mfa
    Require shib-session
</RequireAll>

Apache 2.2

Unfortunately Apache 2.2 does not support the <RequireAll> block and interprets multiple Require directives with an implicit ‘OR’. Shibboleth SP instead provides an equivalent functionality to RequireAll. Note: The ShibRequireAll directive is NOT compatible with Apache 2.4.

AuthType shibboleth
ShibRequestSetting requireSession true
ShibRequestSetting applicationId stepup2f
ShibRequireAll on
ShibCompatWith24 on
 
Require authnContextClassRef https://refeds.org/profile/mfa
Require shib-session

3.2. On IIS, this step has already been handled through configuration of the Path element under RequestMap where we already added the additional parameters authType="Shibboleth" and requireSession="true" along with the <AccessControl> element.

4. Add your new endpoint to your SP’s metadata

When you define an Application Override handlerURL, a new Shibboleth service endpoint is created at that location. Before all your step-up configuration work pays off, you must register the new endpoint(s) with your IdP.

4.1. If your SP is registered with the UW, register new Assertion Consumer Service endpoints (ACS) in the UW Service Provider Registry.

The new Application Override service endpoints will not be returned if you query your metadata endpoint and therefore the UW IdP can’t automatically discover and register them. You must register these manually!

4.2. If your SP is registered with InCommon, submit a request for a metadata update.

4.3. The metadata you register is the same in either case:

Example ACS Creation

If your metadata contains the standard ACS
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST with a value of https://your-host.uw.edu/Shibboleth.sso/SAML2/POST

and you created an Application Override handlerURL="/stepup/Shibboleth.sso"

then you would create a new ACS
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST with a value of https://your-host.uw.edu/stepup/Shibboleth.sso/SAML2/POST

See also