Skip navigation
Documentation

Duo for Confluence

Contents

Duo integrates with Atlassian Confluence to add two-factor authentication to your wiki logins, complete with inline self-service enrollment and authentication prompt. The code is open-source and available on GitHub.

This project has been tested with Confluence 4.2, 5.1, 5.4, 5.6 - 5.10 and 6.0.2 - 6.1.1. It is not compatible with Confluence 4.1. Check your Confluence version before installing Duo. Also note the location of your Confluence installation directory.

First Steps

  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 Confluence in the applications list. Click Protect this Application to get your integration key, secret key, and API hostname. (See Getting Started for help.)
  4. Download the duo_confluence package from GitHub as a zipped file and uncompress the package on your Confluence server.

Install Duo Using a Script

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

Install Duo Manually

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.

If you've already installed Duo using the install script you don't need to do these manual install steps. Skip to Install the Add-on and Configure Confluence.

  1. Install the duo_java JAR

    Copy the prebuilt duo.jar from the unzipped etc directory into the Confluence lib directory.

    cp etc/duo.jar $CONFLUENCE_DIR/confluence/WEB-INF/lib
    
  2. Install the duo_client_java JAR

    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
    
  3. Install the Seraph Filter

    Copy the prebuilt duo-filter-1.3.7.jar from etc into the Confluence lib directory.

    cp etc/duo-filter-1.3.7.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.

Install the Add-on and Configure Confluence

  1. Install the add-on. The add-on provides the UI to send credentials to Duo and post results back.

    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.2.jar file. Click the Upload button.

  2. 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 ikey, skey, akey, and 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 ikey, skey, akey, and 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>
        <init-param>
            <param-name>fail.Open</param-name>
            <param-value>true to fail open, false to fail secure. Default is false.</param-value>
        </init-param>
    </filter>
    

    Locate the security filter-mapping already present in the web.xml file by searching among the <filter-mapping> entries for <filter-name>security</filter-name>. It looks similar to this:

    <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 -->
    

    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>
    
  3. Restart Confluence.

    • Linux: Run the command sudo /etc/init.d/confluence stop ; sudo /etc/init.d/confluence start
    • Windows: Open the "Services" console (services.msc). Locate the Apache Tomcat Confluence service and restart it.

    If you haven't configured Confluence to start with a script or service see the Confluence documentation.

Test your Setup

To test, visit any page which requires authentication. You will need to authenticate with Duo after you have authenticated locally.

Notes

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

Troubleshooting

Need some help? Take a look at our Confluence Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

  1. Confluence connection initiated
  2. Primary authentication
  3. Confluence connection established to Duo Security over TCP port 443
  4. Secondary authentication via Duo Security’s service
  5. Confluence receives authentication response
  6. Confluence session logged in

Appendix: Building Manually

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.

  1. Build the duo_java JAR

    If you'd prefer to build your own duo.jar, the source is available from Github. In a temporary directory:

    git clone git://github.com/duosecurity/duo_java.git
    cd duo_java/DuoWeb
    mvn clean install
    mv target/DuoWeb-1.1-SNAPSHOT.jar duo.jar
    

    After this step, the built JAR can be copied to the Confluence lib directory as described in Install the duo_java JAR.

  2. Build the duo_client_java JAR

    If you'd prefer to build your own duo-client-0.2.1.jar, the source is available from Github. In a temporary directory:

    git clone git://github.com/duosecurity/duo_client_java.git
    cd duo_client_java/duo-client
    mvn clean install
    

    After this step, the built JAR can be copied to the Confluence lib directory as described in Install the duo_client_java JAR

  3. Build the Add-on JAR

    Optionally Customize the Duo Authentication Page

    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.

    Build the JAR

    If you'd prefer to build your own duo-twofactor-1.4.2.jar, it can be built with the Atlassian plugin SDK:

    cd duo_twofactor
    atlas-mvn package
    

    After this step, the built JAR can be installed as described in Install the add-on.

  4. Build the Seraph Filter JAR

    If you'd prefer to build your own duo-filter-1.3.7.jar, it can be built with the Atlassian plugin SDK. 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.

Ready to Get Started?

Sign Up Free