Configuring Your Service Provider for Step-Up Two-Factor Authentication

This document is for U-M information technology staff members. It explains how to configure a Shibboleth Service Provider (SP) to use two-factor authentication, specifically for part of a service. This document builds on the information detailed in Configuring Your Shibboleth Service Provider for Two-Factor Authentication.

What is Step-Up Two-Factor Authentication?

Step-up two-factor authentication requires an individual who is already logged in to a service or website to provide a second factor, such as a tokencode, to access a certain portion of a service. For example, a service could allow all U-M affiliates to access the site https://example.umich.edu, but require a tokencode for those who wanted to access https://example.umich.edu/SecretPortal.

Note: Throughout this document, SecretPortal is used as an example directory of a site or service that will be protected by two-factor authentication. Replace it with the name of the protected directory for your service.

How Does It Work With Shibboleth?

When an individual logs in using Shibboleth, his/her login credentials are verified at login. The session does not continually re-verify his/her credentials, so if he/she is already logged in with a uniqname and UMICH password, there will be no additional login prompt. In order to apply two-factor to an existing Shibboleth session, a new session must be started.

In order to “step-up” an existing Shibboleth session to use two-factor authentication, there are two options.

1. Clear existing sessions Clear the existing session, which will log him/her out and force a login with username, password, and tokencode.

2. Configure the protected portion of the site (SecretPortal) as a separate application Use the shibboleth2.xml file to configure the appropriate directory of your site or service as a separate application with its own session requirements.

1. Define the Content

Once you identify the directory of your SP that requires an extra layer of authentication, you must define it in the configuration file (shibboleth2.xml). This is done using Path statements within a RequestMapper element (see example configurations below). If multiple directories of your SP will use two-factor step-up, those directories must be defined using unique applicationId values.

The RequestMapper definition is a section within the shibboleth2.xml file, but sometimes it is missing from the default shibboleth2.xml file. If it is missing, follow the examples and add it just before the ApplicationDefaults section.

Example Configurations

For a Linux SP using Apache:

<RequestMapper type="Native">
   <RequestMap>
     <Host name="example.umich.edu">
       <Path name="stepup" applicationId="SecretPortal" />
     </Host>
   </RequestMap>
</RequestMapper>

For a Windows SP using IIS:

<RequestMapper type="Native">
   <RequestMap>
     <Host name="example.umich.edu">
       <Path name="stepup" applicationId="SecretPortal" authType="shibboleth" requireSessionWith="duo"/>
     </Host>
   </RequestMap>
</RequestMapper>

2. Configure the Application Override

In your shibboleth2.xml file, locate the example ApplicationOverride at the end of the ApplicationDefaults section, and add an override element that looks like this:

<!-- Step-up 2-factor at U-M -->
<ApplicationOverride id="stepup2f">
   <Sessions lifetime="28800" timeout="3600" checkAddress="false" handlerURL="/SecretPortal/Shibboleth.sso" handlerSSL="false">
     <SessionInitiator type="Chaining" Location="/SecureLogin" isDefault="false" id="duo" relayState="cookie" entityID="https://shibboleth.umich.edu/idp/shibboleth" authnContextClassRef="urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken">
       <SessionInitiator type="SAML2" template="bindingTemplate.html"/>
     </SessionInitiator>
   </Sessions>
</ApplicationOverride>

Additional Information

1. The ApplicationOverride id, which is SecretPortal in the example above, can have any value. However, each Application Override defined must have a unique name, and must match the name(s) provided in the corresponding Path statement(s) defined in the RequestMapper element.

2. The handlerURL value should be / + Path name + / + Shibboleth.sso, so in the example above it is /SecretPortal/Shibboleth.sso because the the Path in the RequestMapper element from step one is named SecretPortal.

3. The SessionInitiator id value, duo in this example, can also be named anything you like, but it must match the requireSessionWith parameter in the Path statement defined in the Windows IIS System example from step one or the ShibRequireSessionWith Apache directive described below in step three.

3. Requesting Step-Up to Two-Factor Authentication

Now that the content has been defined and the Application Override configured, your application needs to request both the application id and the session id.

For a Linux SP using Apache:

authtype shibboleth
ShibRequestSetting applicationId stepup2f
ShibRequireSessionWith duo
shibrequiresession on
require valid-user

For a Windows SP using IIS, this was configured in the Path statement by including authType="Shibboleth" and requireSessionWith="duo".

4. Update Service Provider Metadata

When an Application Override handlerURL is defined, it creates a new Shibboleth service endpoint at that location. Before the configuration will work, the new endpoint(s) must first be registered with the U-M Shibboleth Identity Provider (IdP).

Example Metadata Update

If your metadata contains the standard Assertion Consumer Service (ACS) element:

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https:// /Shibboleth.sso/SAML2/POST" index="10"/>

and you created an Application Override element with:

handlerURL="/SecretPortal/Shibboleth.sso"

then you would create a new ACS as follows:

<md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://example.umich.edu/SecretPortal/Shibboleth.sso/SAML2/POST" index="10"/>