Skip navigation
Documentation

Duo for Confluence - Duo Universal Prompt Public Preview

Last Updated: October 22nd, 2020

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.

Confluence with Duo Universal Prompt support is in Public Preview. Contact duo-frameless-integrations-beta@cisco.com with feedback.

Preparation

  • The Duo Universal Prompt Duo experience supports Confluence 7.5 and later. Check your Confluence version before installing Duo.
  • Note the location of your Confluence installation directory. The default location is /opt/atlassian/confluence.
  • Determine a Redirect URI to which the Duo plugin should redirect back to after successful two-factor authentication. You'll specify this during installation. To redirect back to the Confluence Dashboard after authentication, the Redirect URI would be {Your_Confluence_URL}/index.action, for example: https://confluence.example.com/index.action.

Note that installing Duo may cause issues with application links between Confluence and Jira. Read this for more information.

First Steps

If you already have a previous version of the Duo Confluence plugin installed, follow the steps in the Updating the Duo Plugin section.

  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 the entry for Confluence with a protection type of "2FA" in the applications list. Click Protect to the far-right to configure the application and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications in Duo and additional application options.
  4. Download the duo_universal_atlassian 2.0.0 release package as a zip file from GitHub and uncompress the package on your Confluence server.

Treat your client secret like a password!

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

Duo Universal Prompt

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 Confluence application is a two-step process:

  • Update the Confluence application to support the Universal Prompt.
  • Enable the Universal Prompt experience for users of that Confluence application (when the Universal Prompt becomes available)

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 now, proceed with the installation instructions in this document. If you're updating the Confluence Duo application to a newer version, follow the update directions below.

Universal Prompt Info - Update Available

Once a user authenticates to Confluence via the updated Duo plugin, the "Universal Prompt" section of the Confluence application page reflects this status as "New Prompt Ready".

Universal Prompt Info - Application Updated

When the Universal Prompt becomes available, you'll return here to activate it for users of this application.

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.

Install Duo Using a Script

After running the install script you will edit a configuration file and restart Confluence to complete the setup.

  1. From the command line, run the install.py installer from within the extracted duo-atlassian-plugin-2.0.0-snapshot directory with the following arguments:

    Required Arguments
    --client-id Your Integration key from the Confluence application in the Admin Panel.
    --client-secret Your Secret key from the Confluence application in the Admin Panel.
    --api-host Your Duo API hostname from the Confluence application in the Admin Panel.
    --redirect-url The Redirect URI to which the user is redirected after authentication (i.e. https://confluence.example.com/index.action.)

    Example Syntax:

    ./install.py --confluence --client-id <your_integration_key> --client-secret <your_secret_key> --api-host <your_Duo_API_hostname> --redirect-url <your_redirect_uri>
    Optional Arguments
    --directory The directory where Confluence is installed. Defaults to /opt/atlassian/confluence if not specified.
    --fail-closed Determine whether to permit user access to the application if Duo's service is unreachable. Defaults to allowing user access if not specified.
    --verbose Show detailed output from the installation script.

    If the script is unable to copy the necessary Duo files or update the XML config file, try installing Duo manually.

  2. Restart Confluence.

    • Linux: Run the command 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.

Proceed to testing your Duo 2FA installation.

Install Duo Manually

You do not need to perform the manual install and configure steps if you installed using a script.

Copy the Duo Files

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

  1. Install the duo_java JAR

    Copy the prebuilt duo-filter-2.0.0-SNAPSHOT-jar-with-dependencies.jar from the unzipped etc directory into the Confluence lib directory.

    cp etc/duo-filter-2.0.0-SNAPSHOT-jar-with-dependencies.jar $CONFLUENCE_DIR/confluence/WEB-INF/lib
  2. Follow the instructions to install the add-on and edit your configuration.

Configure Confluence

  1. 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 client.Id, client.Secret, redirecturi, and host, as described in Install Duo Using a Script.

    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 client-id, client-secret, redirect-url, 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>client.Id</param-name>
            <param-value>DXXXXXXXXXXXXXXXXXXX</param-value>
        </init-param>
        <init-param>
            <param-name>client.Secret</param-name>
            <param-value>abcdefghijklmnopqrstuvwxyx0123456789ABCD</param-value>
        </init-param>
        <init-param>
            <param-name>redirecturi</param-name>
            <param-value>https://confluence.example.com/index.action</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>true</param-value>
        </init-param>
    </filter>
    

    Note that this configuration sets the fail.Open setting to true. This means that in the event that Duo's service cannot be contacted, users' authentication attempts will be permitted if primary authentication succeeds. To prevent user logins if Duo's service cannot be contacted, change the fail.Open setting value to false.

    Next, locate 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>
    
  2. 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.

Proceed to testing your Duo 2FA installation.

Test your Setup

To test your setup, log into Confluence. Duo's enrollment or login prompt should appear after you enter your username and password.

Updating the Duo Plugin

Updating the Duo plugin follows the same process as the initial install, with the necessary first step of removing the previously installed plugin. The install script copies the new Duo files into your application and updates the XML configuration with the options specified.

Before updating, determine the installed version of the Duo plugin. Check your $CONFLUENCE_DIR/confluence/WEB-INF/lib directory for the presence of the Duo filter JAR file. The filename indicates the version:

  • duo-filter-2.x.x-SNAPSHOT-jar-with-dependencies.jar - Version 2.0.0 and later.
  • duo-filter-1.x.x.jar - Version 1.4.3 and earlier.

To update your currently installed Duo Confluence plugin:

  1. Duo v1 installs only: Log in to the Confluence administration console and use the top navigation bar to go to the settings menu (gear icon) and select Add-ons or Manage apps. Locate your existing Duo two-factor v1 plugin and disable/uninstall it.

  2. Obtain the latest duo_atlassian_plugin v2 preview release package as a zip file from Duo and uncompress the package on your Confluence server.

  3. Run the install.py script from within the extracted duo-atlassian-plugin-2.0.0-snapshot directory with the following arguments (as described in the first-time install instruction:

    Required Arguments
    --client-id Your Integration key from your existing Confluence application in the Admin Panel.
    --client-secret Your Secret key from your existing Confluence application in the Admin Panel.
    --api-host Your Duo API hostname from the Confluence application in the Admin Panel.
    --redirect-url The Redirect URI to which the user is redirected after authentication (i.e. https://confluence.example.com/index.action)

    Example Syntax:

    ./install.py --confluence --client-id <your_integration_key> --client-secret <your_secret_key> --api-host <your_Duo_API_hostname> --redirect-url <your_redirect_uri>
    Optional Arguments
    --directory The directory where Confluence is installed. Defaults to /opt/atlassian/confluence if not specified.
    --fail-closed Determine whether to permit user access to the application if Duo's service is unreachable. Defaults to allowing user access if not specified.
    --verbose Show detailed output from the installation script.

    If the script is unable to copy the necessary Duo files or update the XML config file, try installing Duo manually to complete the update.

    The install script detects Duo files already present, and if found gives you the option to continue with installing the update or cancel without making any changes.

  4. Restart Confluence.

    • Linux: Run the command 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.

Proceed to testing your updated Duo 2FA installation.

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