Duo integrates with Atlassian Confluence to add two-factor authentication to your wiki logins, complete with inline self-service enrollment and Duo Prompt. The code is open-source and available on GitHub.
Note that installing Duo may cause issues with application links between Confluence and JIRA. Read this for more information.
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!
Migration to Universal Prompt for your Confluence application is a two-step process:
Confluence needs a software update installed to support the Universal Prompt when it's ready. The "Universal Prompt" section reflects this status as "App Update Ready" today. If you're configuring Duo for Confluence for the first time now, we recommend installing the Universal Prompt for Confluence instead. If you want to update your current Confluence Duo application to a newer version, follow the update directions for the Universal Prompt.
Once a user authenticates to Confluence via the updated Duo plugin, the "Universal Prompt" section of the Confluence application page reflects this status as "Waiting on Duo".
When the Universal Prompt becomes available, you'll return here to activate it for users of this application. The status will change to "New Prompt Ready", and you'll see the control here for turning it on or off. Until then, your users continue to experience the current Duo prompt. Your users will also continue to see the current Duo Prompt if you haven't updated your Duo application software.
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.
If you've updated your eligible application so that its update status shows "New Prompt Ready" and you're interested in participating in a private preview of the Universal Prompt experience, please apply using this form.
After running the install script you will edit a configuration file, install an add-on with the Confluence UI, and restart Confluence to complete the setup.
From the command line, run the installer from within the duosecurity-duo_confluence directory with the following arguments:
$ ./install.sh -i <your_ikey> -s <your_skey> -h <your_host> -d <confluence_location>
||Your integration key
||Your secret key|
||Your API hostname
||The directory where Confluence is installed. Defaults to /opt/atlassian/confluence if not specified.|
The script copies Duo JAR files into your Confluence 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 install the add-on and edit your configuration.
To install the Duo add-on for Confluence manually, first find the top directory of your Confluence installation, called
$CONFLUENCE_DIR below. This is usually /opt/atlassian/confluence.
Copy the prebuilt DuoWeb-1.3.jar from the unzipped etc directory into the Confluence lib directory.
cp etc/DuoWeb-1.3.jar $CONFLUENCE_DIR/confluence/WEB-INF/lib
Copy the prebuilt duo-client-0.2.1.jar from the unzipped etc directory into the Confluence lib directory.
cp etc/duo-client-0.2.1.jar $CONFLUENCE_DIR/confluence/WEB-INF/lib
Copy the prebuilt duo-filter-1.4.3.jar from etc into the Confluence lib directory.
cp etc/duo-filter-1.4.3.jar $CONFLUENCE_DIR/confluence/WEB-INF/lib
After manually copying the JAR files, follow the instructions to install the add-on and edit your configuration.
From the Confluence administration console, select Add-ons from the left navigation, then Manage add-ons. Click Upload Add-on and browse to the unzipped etc/duo-twofactor-1.4.3.jar file. Click the Upload button.
Configure Confluence by editing web.xml, located at $CONFLUENCE_DIR/confluence/WEB-INF/web.xml.
You will add a filter, which can intercept web requests, and a filter mapping, which causes all requests to go through the filter.
The Duo filter must be added immediately after the local authentication filter, which has a filter-name of security, and before any subsequent filters.
Use the appropriate values for
host, as described in Install Duo Using a Script.
Your akey is a string that you should generate and keep secret from Duo. It should be at least 40 characters long. You can generate a random string in Python with:
import os, hashlib print hashlib.sha1(os.urandom(32)).hexdigest()
Locate the security filter already present in the web.xml file by searching among the
<filter> entries for
<filter-name>security</filter-name>. It looks similar to this:
<filter> <filter-name>security</filter-name> <filter-class>com.atlassian.confluence.web.filter.ConfluenceSecurityFilter</filter-class> </filter>
Paste the below duoauth filter section immediately after the security filter section in web.xml, using your
API host values:
<!-- the duoauth filter and mapping to add, with appropriate param-value entries --> <filter> <filter-name>duoauth</filter-name> <filter-class>com.duosecurity.seraph.filter.DuoAuthFilter</filter-class> <init-param> <param-name>ikey</param-name> <param-value>DXXXXXXXXXXXXXXXXXXX</param-value> </init-param> <init-param> <param-name>skey</param-name> <param-value>abcdefghijklmnopqrstuvwxyx0123456789ABCD</param-value> </init-param> <init-param> <param-name>akey</param-name> <param-value>at_least_40_random_characters_you_make_up</param-value> </init-param> <init-param> <param-name>host</param-name> <param-value>api-XXXXXXXX.duosecurity.com</param-value> </init-param> <!-- set fail.Open to true to fail open or false to fail secure --> <init-param> <param-name>fail.Open</param-name> <param-value>false</param-value> </init-param> </filter>
This is the security filter-mapping already present in the web.xml file.
<filter-mapping> <filter-name>security</filter-name> <url-pattern>/*</url-pattern> <dispatcher>REQUEST</dispatcher> <dispatcher>FORWARD</dispatcher> <!-- we want security to be applied after urlrewrites, for example --> </filter-mapping>
Paste the below duoauth filter-mapping section immediately after the security filter-mapping section in web.xml.
<filter-mapping> <filter-name>duoauth</filter-name> <url-pattern>/*</url-pattern> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> </filter-mapping>
sudo /etc/init.d/confluence stop ; sudo /etc/init.d/confluence start
If you haven't configured Confluence to start with a script or service see the Confluence documentation.
To test your setup, log into Confluence. Duo's enrollment or login prompt should appear after you enter your username and password.
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.
Please see the instructions for updating the v1.x Confluence plugin to the Duo Atlassian 2.x plugin, featuring support for the Duo Universal Prompt.
To deactivate the filter, remove or comment out the filter mapping from web.xml and restart Confluence. Duo authentication is no longer required.
XML-RPC and SOAP are not authenticated with Seraph unless an empty authentication token is used. For more information, see Managing Confluence Users - Authentication
JARs and templates are located in the etc directory. If you'd prefer to build your own JARs, here is how to do it. The add-on JAR must be rebuilt if you want to customize the Duo authentication page.
Build the duo web JAR
If you'd prefer to build your own DuoWeb-1.3.jar, the latest duo_java release source is available from Github. It can be built with the Atlassian plugin SDK. In a temporary directory:
git clone git://github.com/duosecurity/duo_java.git cd duo_java/DuoWeb atlas-mvn install
After this step, the built JAR can be copied to the Confluence lib directory as described in Install the duo web JAR.
Build the duo client JAR If you'd prefer to build your own duo-client-0.2.1.jar, the duo_client_java source is available from Github. It can be build with the Atlassian plugin SDK. In a temporary directory:
git clone git://github.com/duosecurity/duo_client_java cd duo_client atlas-mvn install
After this step, the built JAR can be copied to the Confluence lib directory as described in Install the duo_client_java JAR
Build the Add-on JAR
The authentication page template is duo_twofactor/src/main/resources/duologin.vm. It can be used as-is, or styled to match your organization.
If you want the Duo authentication page to include other resources, such as scripts or images, put them in the resources directory as well, and edit atlassian-plugin.xml to add them to the served resources. After customizing, rebuild and install the JAR.
If you'd prefer to build your own duo-twofactor-1.4.3.jar, it can be built with the Atlassian plugin SDK from the latest duo_confluence release source from GitHub:
cd duo_twofactor atlas-mvn package
After this step, the built JAR can be installed as described in Install the add-on.
Build the Seraph Filter JAR
If you'd prefer to build your own duo-filter-1.4.3.jar, i it can be built with the Atlassian plugin SDK from the latest duo_confluence release source from GitHub.
The seraph filter has duo_java and duo_client_java as build dependencies. Please follow the instructions for manually building duo_java and duo_client_java before attempting a manual build of the seraph filter.
cd duo_seraph_filter atlas-mvn package
After this step, the built JAR can be installed as described in Install the Seraph filter.