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+.
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.
Before starting:
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!
Duo's next-generation authentication experience, the Universal Prompt, is coming to web-based applications that display the current Duo Prompt in browsers.
Migration to Universal Prompt for your Shibboleth application is a two-step process:
Shibboleth needs an update to support the Universal Prompt when it's ready, but the update isn't available yet. The "Universal Prompt" section reflects this status as "Waiting on App Provider". Please refer to the Shibboleth community for information about Duo Universal Prompt support for Shibboleth, or contact Duo Support.
After Shibboleth includes the necessary changes you may need to install an application update or upgrade on your server to obtain Duo Universal Prompt support.
You'll later return to the settings on this page to activate the Universal Prompt for your Shibboleth users once we've released it.
Click the See Update Progress link to view the Universal Prompt Update Progress report. This report shows the update availability and migration progress for all your Duo applications in-scope for Universal Prompt support.Read the Universal Prompt Update Guide for more information about the update process to support the new prompt, and watch the Duo Blog for future updates about the Duo Universal Prompt.
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.
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>
-i |
Your integration key
(i.e. DIXXXXXXXXXXXXXXXXXX )
|
-s |
Your secret key |
-h |
Your API hostname
(i.e. api-XXXXXXXX.duosecurity.com )
|
-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.
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.
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/
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/
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/
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/
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/
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.
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()
Open idp.properties file located at $SHIBBOLETH_DIR/conf/idp.properties. Add the following values at the end of the file:
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”). |
duo.failmode
|
Either "safe" or "secure":
|
For example:
#Duo Configuration
duo.ikey = DIXXXXXXXXXXXXXXXXXX
duo.skey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
duo.akey = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
duo.host = api-XXXXXXXX.duosecurity.com
duo.failmode = safe
Edit the conditions-flow.xml file located at $SHIBBOLETH_DIR/flows/authn/conditions/conditions-flow.xml.
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 -->
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>
Run the following to rebuild the Shibboleth WAR file:
/opt/shibboleth-idp/bin/build.sh
Restart your web server for the changes to take effect.
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.
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.
If you'd prefer to build your own JAR files to use with Shibboleth please follow the steps below:
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/
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/
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.