Duo for Jira 6 and 7 - Legacy Plugin

End of Support Information

The last date of support for Duo's two-factor solution for Jira Server was February 14, 2024. This coincides with Atlassian's end of support for Jira 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 Jira application before February 14, 2024:

• Your existing Duo Jira 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_jira 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 Jira applications in the Duo Admin Panel.
• No new Duo Jira 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 Jira Data Center.

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

• No new Duo Jira 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 Jira Data Center.

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

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

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

Overview

This plugin was intended for on-premises installations of JIRA 6.1 and 7. Mobile browsers may experience issues logging on with two-factor.

Check your JIRA version before installing Duo. Also note the location of your JIRA installation directory.

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

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 the entry for Jira 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 latest duo_jira release package as a zip file from GitHub and uncompress the package on your JIRA 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

Read the Universal Prompt Update Guide for more information about the update process and the new login experience for users.

Migration to Universal Prompt for your Jira application is a three-step process:

1. Install an update for the Jira 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 Jira application if the traditional prompt is still selected. Once activated, all users of the application see the Duo Universal Prompt in a redirect.

New Jira Applications

If you're configuring Duo for Jira for the first time now, we recommend installing the updated Universal Prompt application for Jira instead of the legacy application described on this page, so your users can experience the Universal Prompt as soon as you finish the Duo configuration steps.

Existing Jira Applications

Jira needs a software update installed before you can activate the Universal Prompt experience. The "Universal Prompt" section reflects this status as "Update Required" today.

To update your current Jira Duo application to a newer version so that you can activate the Universal Prompt experience, follow the update directions for the Universal Prompt.

You **must** perform a Duo 2FA authentication after performing the required update. This authentication will not yet show the Universal Prompt, but will update the status of that application in Duo's service to unlock the Universal Prompt activation control so you can then turn it on for the application if the traditional prompt is still selected. Your users continue to see the current Duo prompt experience until you apply the update and authenticate using the updated application, and then activate Universal Prompt for that application.

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, install an add-on with the JIRA UI, and restart JIRA to complete the setup.

From the command line, run the installer from within the duosecurity-duo_jira directory with the following arguments:

$ ./install.sh -i <your_ikey> -s <your_skey> -h <your_host> -d <jira_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 JIRA is installed. Defaults to /opt/atlassian/jira if not specified.

The script copies Duo JAR files into yourJIRA 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 plugin for JIRA manually, first find the top directory of your JIRA installation, called $JIRA_DIR below. This is usually /opt/atlassian/jira.

If you've already installed Duo using the install script you don't need to do these manual install steps. Skip to Configure JIRA.

1. Install the duo web JAR

   Copy the prebuilt DuoWeb-1.3.jar from the unzipped etc directory into the JIRA lib directory.

    cp etc/DuoWeb-1.3.jar $JIRA_DIR/atlassian-jira/WEB-INF/lib
   

2. Install the duo client JAR

   Copy the prebuilt duo-client-0.2.1.jar from the unzipped etc directory into the JIRA lib directory.

    cp etc/duo-client-0.2.1.jar $JIRA_DIR/atlassian-jira/WEB-INF/lib
   

3. Install the Seraph Filter

   Copy the prebuilt duo-filter-1.4.3.jar from etc into the JIRA lib directory.

    cp etc/duo-filter-1.4.3.jar $JIRA_DIR/atlassian-jira/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 JIRA

1. Install the Plugin

   The plugin provides the UI to send credentials to Duo and post results back.

   From the JIRA 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.

2. Configure JIRA by editing web.xml, located at $JIRA_DIR/atlassian-jira/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()
   

   This is the security filter already present in the web.xml file.

    <filter>
    	<filter-name>security</filter-name>
    	<filter-class>com.atlassian.jira.security.JiraSecurityFilter</filter-class>
    </filter>
   

   Paste the below duoauth filter section immediately after the security filter section in web.xml, using your ikey, skey, akey, and 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>
   

3. Restart JIRA.

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

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

Test your Setup

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

Updating the Duo Plugin

Please see the instructions for updating the v1.x Jira plugin to the Duo Atlassian 2.x plugin, featuring support for the Duo Universal Prompt.

Notes

To deactivate the filter, remove or comment out the filter mapping from web.xml and restart JIRA. Duo authentication is no longer required.

Troubleshooting

Need some help? Take a look at the JIRA Frequently Asked Questions (FAQ) page or try searching our JIRA Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

1. Jira connection initiated
2. Primary authentication
3. Jira connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service
5. Jira receives authentication response
6. Jira 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 plugin JAR must be rebuilt if you want to customize the Duo authentication page.

1. 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 JIRA lib directory as described in Install the duo web JAR.

2. 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 JIRA lib directory as described in Install the duo_client_java JAR

3. Build the Plugin 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.3.jar, it can be built with the Atlassian plugin SDK from the latest duo_jira release source from GitHub:

    cd duo_twofactor
    atlas-mvn package
   

   After this step, the built JAR can be installed as described in Install the plugin.

4. Build the Seraph Filter JAR

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