Duo for Confluence - Duo Universal Prompt

End of Support Information

The last date of support for Duo's two-factor solution for Confluence Server was February 14, 2024. This coincides with Atlassian's end of support for Confluence Server.

Duo will no longer provide updates or fixes for this application, and Duo Support will not provide configuration or troubleshooting assistance.

If you created a Duo Confluence application before February 14, 2024:

• Your existing Duo Confluence installation will continue providing two-factor authentication for user logins past the end of support of the traditional Duo Prompt on March 30, 2024 if you deployed the duo_universal_atlassian plugin.
  • If you still use the legacy duo_confluence plugin, it will keep working after March 30, 2024 but will cease working when the future end-of-life date of the traditional Duo Prompt arrives.
• You may view and manage existing Duo Confluence applications in the Duo Admin Panel.
• No new Duo Confluence applications may be created in the Duo Admin Panel.
• Duo no longer provides support or troubleshooting help, except as needed to assist you with migration to Duo Single Sign-On with Atlassian Cloud or Confluence Data Center.

If you did not create a Duo Confluence application before February 14, 2024:

• No new Duo Confluence applications may be created in the Duo Admin Panel.
• Duo no longer provides support or troubleshooting help, except as needed to assist you with migration to Duo Single Sign-On with Atlassian Cloud or Confluence Data Center.

We recommend that you migrate your on-premises Confluence application to Atlassian Cloud and add Duo login protection with Duo Single Sign-On for Atlassian Cloud.

If you opt to deploy Confluence Data Center, you can add Duo login protection with Duo Single Sign-On for Generic SAML Service Providers. The duo_universal_atlassian or duo_confluence MFA plugins are not valid for Confluence Data Center.

Review the Duo End of Sale, Last Date of Support, and End of Life Policy.

The Duo Universal Prompt Duo experience worked with on-premises installations of Confluence 7.4 and later v7.x Confluence versions. Please see the Duo Knowledge Base for more information about known issues with Duo and Confluence 8.

Prerequisites

1. Check your Confluence version before installing Duo. You need to be running 7.4 or a later v7.x version to use this Duo plugin. If you're running an earlier version of Confluence and can't upgrade, see the Duo legacy Confluence plugin instructions.

   Do not install Duo on Confluence 8 or upgrade a Confluence v7.x install with Duo to Confluence 8. See the Duo Knowledge Base for details about Confluence 8 compatibility.

2. Note the location of your Confluence installation directory. The default location is /opt/atlassian/confluence.

3. 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. The URI must use https and specify the server by hostname, not by IP address, with a maximum length of 1024 characters.

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

Compatibility Notes

• Certain Confluence plugin combinations can result in Jackson dependency conflicts with the duo_universal_atlassian plugin. Please use this modified release if you encounter jar dependency errors in Confluence.

• Confluence 7.14.1 and later include a significantly different and minimal web.xml file that the supplied installation script may not update correctly. For these versions, you will need to configure Confluence manually by inserting the Duo <filter> and <filter-mapping> sections anywhere within the main web-app block.

First Steps

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

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications → Protect an Application.
3. Locate the 2FA-only entry for Confluence in the applications list. Click Protect to the far-right to configure the application and get your Client ID, Client secret, 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.
   
   

   Previously, the Client ID was called the "Integration key" and the Client secret was called the "Secret key".

4. Download the latest duo_universal_atlassian 2.x.x release package as a zip file from GitHub and uncompress the package on your Confluence server.

Duo Universal Prompt

The Duo Universal Prompt provides a simplified and accessible Duo login experience for web-based applications, offering a redesigned visual interface with security and usability enhancements.

Universal Prompt	Traditional Prompt

For Confluence applications created before March 2024, migration to Universal Prompt is a three-step process:

1. Install an update for the Confluence application, which implements a redirect to Duo during authentication to support the Universal Prompt.
2. Authenticate with Duo 2FA using the updated application so that Duo makes the Universal Prompt activation setting available in the Admin Panel. This first authentication after updating shows the traditional Duo prompt in a redirect instead of an iframe.
3. From the Duo Admin Panel, activate the Universal Prompt experience for users of that Duo Confluence application if the traditional prompt is still selected. Once activated, all users of the application see the Duo Universal Prompt in a redirect.

If you created your Confluence application before March 2024, it's a good idea to read the Universal Prompt Update Guide for more information, about the update process and the new login experience for users, before you activate the Universal Prompt for your application.

New Confluence Applications

When you install the latest version of Duo for Confluence you're ready to use the Universal Prompt. Confluence applications created after March 2024 have the Universal Prompt activated by default. If you're configuring Confluence now, proceed with the installation instructions in this document.

The "Universal Prompt" area of the application details page shows that this application is "Activation complete", with these activation control options:

• Show traditional prompt: Your users experience Duo's traditional prompt via redirect when logging in to this application.
• Show new Universal Prompt: (Default) Your users experience the Universal Prompt via redirect when logging in to this application.

Existing Confluence Applications

Duo for Confluence needs a software update installed to support the Universal Prompt. The "Universal Prompt" section of your existing Confluence application reflects this status as "Update required". To update Duo for Confluence application to a newer version, follow the update directions below.

Once a user authenticates to Duo for Confluence via the updated Duo plugin, the "Universal Prompt" section of the Confluence application page reflects this status as "Ready to activate", with these activation control options:

• Show traditional prompt: (Default) Your users experience Duo's traditional prompt via redirect when logging in to this application.
• Show new Universal Prompt: Your users experience the Universal Prompt via redirect when logging in to this application.

In addition, the "Integration key" and "Secret key" property labels for the application update to "Client ID" and "Client secret" respectively. The values for these properties remain the same.

Activate Universal Prompt

Activation of the Universal Prompt is a per-application change. Activating it for one application does not change the login experience for your other Duo applications.

Enable the Universal Prompt experience by selecting Show new Universal Prompt, and then scrolling to the bottom of the page to click Save.

Once you activate the Universal Prompt, the application's Universal Prompt status shows "Activation Complete" here and on the Universal Prompt Update Progress report.

Should you ever want to roll back to the traditional prompt, you can return to this setting and change it back to Show traditional prompt. However, this will still deliver the Duo prompt via redirect, not in an iframe. Keep in mind that support for the traditional Duo prompt ended for the majority of applications in March 2024.

Universal Update Progress

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. You can also activate the new prompt experience for multiple supported applications from the report page instead of visiting the individual details pages for each application.

Install Duo Using a Script

After running the install script you will edit a configuration file and restart Confluence to complete the setup. Be sure to uncompress the downloaded duo_universal_atlassian 2.x.x release zip on your server first and note the path to the extracted directory (it will reflect the version you downloaded, like duo-atlassian-plugin-2.0.0-snapshot).

1. From the command line, run the install.py installer from within the extracted duo-atlassian-plugin-2.x.x-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). Must be a well-formed with a valid HTTPS URL and port, using a hostname.

   Example Syntax:

   ./install.py --confluence --client-id <your_integration_key_or_client_id> --client-secret <your_secret_key_or_client_secret> --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. Confluence 7.14.1 and later include a significantly different and minimal web.xml file that the script may not update correctly. For these versions, you will need to configure Confluence 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. Uncompress the downloaded duo_universal_atlassian 2.x.x release zip on your server and note the path to the extracted directory (it will reflect the version you downloaded, like duo-atlassian-plugin-2.0.0-snapshot).

2. Copy the prebuilt duo-filter-2.x.x-SNAPSHOT-jar-with-dependencies.jar from the unzipped etc directory into the Confluence WEB-INF/lib directory. Note that the JAR file name will contain the actual release version, like duo-filter-2.0.0-SNAPSHOT-jar-with-dependencies.jar.

   cp etc/duo-filter-2.x.x-SNAPSHOT-jar-with-dependencies.jar $CONFLUENCE_DIR/confluence/WEB-INF/lib

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

Use the appropriate values for client.Id, client.Secret, redirecturi, and host, as described in Install Duo Using a Script.

Confluence 7.14.1 and later include a significantly different and minimal web.xml file. For these versions, you can insert the Duo <filter> and <filter-mapping> sections anywhere within the main web-app block while configuring Confluence.

In Confluence version 7.14.0 and earlier, the Duo filter must be added immediately after the local authentication filter, which has a **filter-name** of **security**, and before any subsequent filters. 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 for 7.14.0 and earlier, or anywhere in web.xml for 7.14.1 and later, 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 if your server runs Confluence 7.14.0 or earlier.

	<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 for 7.14.0 and earlier, or anywhere in web.xml for 7.14.1 and later:

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

Proceed to testing your Duo 2FA installation.

Test your Setup

To test your setup, log into Confluence. Successful verification of your username and password redirects you to Duo. Complete Duo two-factor authentication when prompted and then you'll return to Confluence to complete the login process.

*Universal Prompt experience shown.

Update 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.x.x release package as a zip file from Duo and uncompress the package on your Confluence server. Note the path to the extracted directory (it will reflect the version you downloaded, like duo-atlassian-plugin-2.0.0-snapshot).

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

   Required Arguments

   --client-id	Your Integration key or Client ID from your existing Confluence application in the Admin Panel.
   --client-secret	Your Secret key or Client Secret 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). Must be a well-formed with a valid HTTPS URL and port, using a hostname.

   Example Syntax:

   ./install.py --confluence --client-id <your_integration_key_or_client_id> --client-secret <your_secret_key_or_client_secret> --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. Confluence 7.14.1 and later include a significantly different and minimal web.xml file that the script may not update correctly. For these versions, you will need to configure Confluence manually.

   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.

After upgrading from the v1.x Duo plugin, authenticate once with the v2.x Duo plugin, which will show the traditional Duo Prompt in a redirect instead of the iframe. After that you can activate Universal Prompt for your application.

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. User completes Duo two-factor authentication via the interactive web prompt served from Duo's service and their selected authentication factor.
5. Confluence receives authentication response
6. Confluence session logged in