Skip navigation

Duo Security is now a part of Cisco

About Cisco

Contact Sales Free Trial

Try Duo's trusted access solution now.

Free Trial
Documentation

Duo for Shibboleth Identity Provider v3

Last Updated: March 13th, 2020

Contents

Related

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

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 or later. See the DuoAuthnConfiguration documentation for more information about the built-in Duo flow in Shibboleth v3.3+.

Connectivity Requirements

This application communicates with Duo's service on TCP port 443. Firewall configurations that restrict outbound access to Duo's service with rules using destination IP addresses or IP address ranges aren't recommended, since these may change over time to maintain our service's high availability. If your organization requires IP-based rules, please review this Duo KB article.

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.

Treat your secret key like a password

The security of your Duo application is tied to the security of your secret key (skey). Secure it as you would any sensitive credential. Don't share it with unauthorized individuals or email it to anyone under any circumstances!

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.

Enable Hostname Whitelisting

If you plan to permit use of WebAuthn authentication methods (security keys, U2F tokens, or Touch ID), Duo recommends enabling hostname whitelisting for this application and any others that show the inline Duo Prompt before onboarding your end-users.

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.