Duo for Shibboleth Identity Provider v3

This plugin has been tested with Shibboleth Identity Provider v3.1.1.

Shibboleth v3.3 and later include a native Duo authentication login flow. Please do not try to use the instructions on this page with Shibboleth v3.3. See the DuoAuthnConfiguration documentation for more information about the built-in Duo flow in Shibboleth v3.3.

First Steps

Before starting:

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications.
3. Click Protect an Application and locate Shibboleth in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.)
4. Use NTP to ensure that your server's time is correct.
5. Copy the duo_shibboleth.zip file downloaded from GitHub onto your Shibboleth server.

The duo_shibboleth plugin performs a second factor authentication after primary authentication, so you will need a working service provider configured with Shibboleth before continuing.

Install Duo Using a Script

From the command line, run the installer from within the duo_shibboleth/v3 directory with the following arguments:

$ ./install.sh -i <your_ikey> -s <your_skey> -h <your_host> -d <shibboleth_location>

Required Arguments

-i	Your integration key (i.e. DIXXXXXXXXXXXXXXXXXX)
-s	Your secret key
-h	Your API hostname (i.e. api-XXXXXXXX.duosecurity.com)

Optional Arguments

-d	The directory where Shibboleth is installed. Defaults to /opt/shibboleth-idp if not specified.

The script copies Duo configuration files into your Shibboleth install directory. If the script is unable to copy the necessary Duo files, try installing Duo manually.

After running the install script, follow the instructions to Configure the Identity Provider.

Install Duo Manually

To install the Duo plugin for Shibboleth manually, first find the top directory of your Shibboleth installation, called $SHIBBOLETH_DIR below. This is usually /opt/shibboleth-idp.

If you've already installed Duo using the install script you don't need to perform these manual install steps. Skip to Configure the Identity Provider.

1. Install the duo_java JAR from the duo_shibboleth/v3 directory.

   Copy the prebuilt duo.jar from the unzipped plugin directory into the Shibboleth lib directory.

   cp IDP_HOME/edit-webapp/WEB-INF/lib/DuoWeb-1.2-SNAPSHOT.jar $SHIBBOLETH_DIR/edit-webapp/WEB-INF/lib/
   

2. Install the duo_client_java JAR from the duo_shibboleth/v3 directory.

   Copy the prebuilt duo-client-0.2.1.jar from the unzipped plugin directory into the Shibboleth lib directory.

   cp IDP_HOME/edit-webapp/WEB-INF/lib/duo-client-0.2.1-jar-with-dependencies.jar $SHIBBOLETH_DIR/edit-webapp/WEB-INF/lib/
   

3. Install the DuoShibboleth-1.0 JAR from the duo_shibboleth/v3 directory.

   Copy the prebuilt DuoShibboleth-1.0.jar from the unzipped plugin directory into the Shibboleth edit-webapp/WEB-INF/lib directory.

   cp IDP_HOME/edit-webapp/WEB-INF/lib/DuoShibboleth-1.0.jar $SHIBBOLETH_DIR/edit-webapp/WEB-INF/lib/
   

4. Install the Duo-Web-v2 JavaScript file from the duo_shibboleth/v3 directory.

   Copy the Duo-Web-v2.min.js from the unzipped plugin directory into Shibboleth edit-webapp/js directory. If the js directory does not already exist, create it.

   cp IDP_HOME/edit-webapp/js/Duo-Web-v2.min.js $SHIBBOLETH_DIR/edit-webapp/js/
   

5. Install the Duo Velocity Macro from the duo_shibboleth/v3 directory.

   Copy duo.vm from the unzipped plugin directory into the Shibboleth views directory.

   cp IDP_HOME/views/duo.vm $SHIBBOLETH_DIR/views/
   

6. Install the Duo Spring Webflow from the duo_shibboleth/v3 directory.

   Copy duo-authn-flow.xml from the unzipped plugin directory into the Shibboleth flows/authn/Duo directory. If the Duo directory does not already exist, create it.

   cp IDP_HOME/flows/authn/Duo/duo-authn-flow.xml $SHIBBOLETH_DIR/flows/authn/Duo/
   

   After manually copying the files, follow the Configure the Identity Provider instructions.

Configure the Identity Provider

Generate an akey

Your application secret key (or akey) is a string that you should generate and keep secret from Duo. It should be at least 40 characters long and stored alongside your integration key and secret key in a configuration file.

You can generate a random string in Python with:

import os, hashlib
print hashlib.sha1(os.urandom(32)).hexdigest()

Edit idp.properties

Open idp.properties file located at $SHIBBOLETH_DIR/conf/idp.properties. Add the following values at the end of the file:

Required

duo.ikey	Your Duo integration key.
duo.skey	Your Duo secret key.
duo.akey	Your Duo application key that you created earlier.
duo.host	Your Duo API hostname (e.g. “api-XXXXXXXX.duosecurity.com”).

Optional

duo.failmode

Either "safe" or "secure": "safe" In the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds. (Default) "secure" In the event that Duo's service cannot be contacted, all users' authentication attempts will be rejected.

For example:

#Duo Configuration
duo.ikey = DIXXXXXXXXXXXXXXXXXX
duo.skey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
duo.akey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
duo.host = api-XXXXXXXX.duosecurity.com
duo.failmode = safe

Edit conditions-flow.xml

Edit the conditions-flow.xml file located at $SHIBBOLETH_DIR/flows/authn/conditions/conditions-flow.xml.

1. Add the following to the top of the <action-state id="ValidateUsernamePassword"> section:

   <!-- Enable Duo Two-Factor Authentication -->
   <evaluate expression="ValidateUsernamePassword" />
   <evaluate expression="'duo'" />
   <transition on="duo" to="DuoAuth" />
   <!-- End Duo Two-Factor Authentication -->
   

2. Add the following directly before </flow> at the bottom of the file:

   <subflow-state id="DuoAuth" subflow="authn/Duo">
       <input name="calledAsSubflow" value="true" />
       <transition on="proceed" to="proceed" />
   </subflow-state>
   

Rebuild WAR file

Run the following to rebuild the Shibboleth WAR file:

/opt/shibboleth-idp/bin/build.sh

Restart Web Server

Restart your web server for the changes to take effect.

Test Your Setup

Start the identity provider and authenticate against it with a Shibboleth service provider. You are prompted to enroll with Duo after authenticating to Shibboleth.

After completing enrollment you'll see the Duo authentication prompt during all subsequent Shibboleth logins.

Network Diagram

1. Application or Service connection initiated
2. Primary authentication
3. Client connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service
5. Shibboleth client receives authentication response.
6. Application or Service session logged in

Appendix: Building Manually

Build the JAR files

If you'd prefer to build your own JAR files to use with Shibboleth please follow the steps below:

1. duo-client-0.2.1-jar-with-dependencies.jar:

   git clone https://github.com/duosecurity/duo_client_java
   cd duo_client_java/duo-client
   mvn package
   cp target/duo-client-0.2.1-jar-with-dependencies.jar $SHIBBOLETH_DIR/edit-webapp/WEB-INF/lib/

2. DuoWeb-1.2-SNAPSHOT.jar:

   git clone https://github.com/duosecurity/duo_java
   cd duo_java/DuoWeb
   mvn package
   cp target/DuoWeb-1.2-SNAPSHOT.jar $SHIBBOLETH_DIR/edit-webapp/WEB-INF/lib/

3. DuoShibboleth-1.0.jar:

   git clone https://github.com/duosecurity/duo_shibboleth
   cd duo_shibboleth/v3/DuoShibboleth
   mvn package
   cp DuoShibboleth-1.0.jar SHIBBOLETH_DIR/edit-webapp/WEB-INF/lib/

If you would like to utilize a manually built dependent JAR when building DuoShibboleth, then copy the respective JARs to IDP_HOME/edit-webapp/WEB-INF/lib before building.