Skip navigation
Documentation

Duo for Shibboleth Identity Provider v3

Duo integrates with Shibboleth to add two-factor authentication for Shibboleth identity providers, complete with inline self-service enrollment and authentication prompt. The code is open-source and available on GitHub.

First Steps

This plugin has been tested with Shibboleth Identity Provider 3.1.1.

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.

Troubleshooting

Need some help? Take a look at the Shibboleth Frequently Asked Questions (FAQ) page or try searching our Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

Duo Shibboleth 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.

Ready to Get Started?

Sign Up Free