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.
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.
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>
||Your integration key
||Your secret key|
||Your API hostname
||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.
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/
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/
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/
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/
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:
||Your Duo integration key.|
Your Duo secret key.
Your Duo application key that you created earlier.
||Your Duo API hostname (e.g. “api-XXXXXXXX.duosecurity.com”).|
Either "safe" or "secure":
#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:
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:
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/
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/
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.