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.
Clear existing sessions Clear the existing session, which will log him/her out and force a login with username, password, and tokencode.
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.
For a Linux SP using Apache:
<Path name="stepup" applicationId="SecretPortal" />
For a Windows SP using IIS:
<Path name="stepup" applicationId="SecretPortal" authType="shibboleth" requireSessionWith="duo"/>
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 -->
<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"/>
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.
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.
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:
ShibRequestSetting applicationId stepup2f
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).
If your SP is not yet registered with U-M, please submit the Shibboleth Configuration Request Form. An example update is below.
If your SP is already registered with U-M, please send an updated copy of your metadata to firstname.lastname@example.org. An example configuration is below.
If your SP is registered with other IdPs, such as InCommon, you will need to update your metadata with those as well.
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:
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"/>