Skip navigation
Documentation

Duo for Jira Software - Duo Universal Prompt

Last Updated: October 13th, 2021

Duo integrates with the on-premises Atlassian Jira Software project and issue tracking application to add two-factor authentication to your logins, complete with inline self-service enrollment and Duo Prompt. The code is open-source, and available on GitHub.

The Duo Universal Prompt Duo experience supports on-premises installations of Jira Software 8.5 and later (not including Jira Service Desk).

Prerequisites

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

  2. Note the location of your Jira installation directory. The default location is /opt/atlassian/jira.

  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 Jira Dashboard after authentication, the Redirect URI would be {Your_Jira_URL}/secure/Dashboard.jspa, for example: https://jira.example.com/secure/Dashboard.jspa. 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.

First Steps

If you already have a previous version of the Duo Jira 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.
  3. Click Protect an Application and locate the 2FA-only entry for Jira 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 Jira 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

The new 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
 Duo Push in Universal Prompt  Duo Push in Traditional Prompt

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

  • Install an update for the Jira application to support the Universal Prompt.
  • Activate the Universal Prompt experience for users of that Duo Jira application.

Before you activate the Universal Prompt for your application, 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.

New Jira Applications

When you install the latest version of Duo for Jira you're ready to use the Universal Prompt. If you're configuring Jira now, proceed with the installation instructions in this document.

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

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

Universal Prompt Info - Application Ready for Universal Prompt

Existing Jira Applications

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

Universal Prompt Info - Update Available

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

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

Universal Prompt Info - Application Ready for Universal Prompt

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 "Update Complete" here and on the Universal Prompt Update Progress report.

Universal Prompt Info - Universal Prompt Activation Complete

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.

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 in-scope for Universal Prompt support. 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 Jira 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 Jira application in the Admin Panel.
    --client-secret Your Secret key from the Jira application in the Admin Panel.
    --api-host Your Duo API hostname from the Jira application in the Admin Panel.
    --redirect-url The Redirect URI to which the user is redirected after authentication (i.e. https://jira.example.com/secure/Dashboard.jspa). Must be a well-formed with a valid HTTPS URL and port, using a hostname.

    Example Syntax:

    ./install.py --jira --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 Jira is installed. Defaults to /opt/atlassian/jira 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 Jira.

    • Linux: Run the command sudo /etc/init.d/jira stop ; sudo /etc/init.d/jira start

    If you haven't configured Jira to start with a script or service see the Jira 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 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. 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 Jira 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 $JIRA_DIR/atlassian-jira/WEB-INF/lib
  3. Follow the instructions to edit your Jira configuration.

Configure Jira

  1. 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 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.jira.security.JiraSecurityFilter</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://jira.example.com/secure/Dashboard.jspa</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 closed -->
        <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 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.

Proceed to testing your Duo 2FA installation.

Test your Setup

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

OIDC Duo Prompt *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 $JIRA_DIR/atlassian-jira/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 Jira plugin:

  1. Duo v1 installs only: Log in to the Jira 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 Jira 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 Jira application in the Admin Panel.
    --client-secret Your Secret key or Client Secret from your existing Jira application in the Admin Panel.
    --api-host Your Duo API hostname from the Jira application in the Admin Panel.
    --redirect-url The Redirect URI to which the user is redirected after authentication (i.e. https://jira.example.com/secure/Dashboard.jspa). Must be a well-formed with a valid HTTPS URL and port, using a hostname.

    Example Syntax:

    ./install.py --jira --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 Jira is installed. Defaults to /opt/atlassian/jira 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 Jira.

    • Linux: Run the command sudo /etc/init.d/jira stop ; sudo /etc/init.d/jira start

    If you haven't configured Jira to start with a script or service see the Jira 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 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