Skip to main content

ALM Connection to Jira Software

How to connect piplanning.io with Jira Software (Cloud or Data Center). This document includes all the steps for using either OAuth (recommended) or Basic Authentication.

Updated today

Step #1: Create a Service User account in Jira

Strong recommendation to use a Service User account in Jira to authenticate. Ensure the Jira Service User account has the required permissions to the Jira Projects Teams/ARTs/ST use.

Note: Ensure the Jira Service User does not need to login via Single Sign On if such a solution is in place.

Required Permissions for the Jira [Service] User

The Jira [Service] User account used for authenticating the ALM Connection needs to have the following permissions in all Jira Projects you want to synchronize (map) with piplanning.io:

  • Project Admin (Recommended)

  • Browse Project/s

  • Create Issues

  • Edit Issues

  • Delete Issues (Optional)

  • Link Issues

  • Schedule Issues

  • Workflow Properties / Edit Workflows - Workflow Access (Recommended)

  • Manage Sprints (Recommended)

  • Modify Reporter (Recommended)

Step #2: Create the ALM Connection to Jira

Prerequisite: Log in to Jira with the Jira Service User account in a browser tab.

  1. Navigate to RTE Cockpit > ALM Connections

  2. Click Add new ALM Connection

  3. Select ALM Tool select Jira. Click Next

IF you wish to use OAuth continue here.

IF you wish to use Basic Auth continue here.

Atlassian advises using OAuth for integration to Jira Cloud.

OAuth is therefore the preferred method for connecting to Jira Cloud.

Basic Auth is preferred to only to be used if there are issues with OAuth.

OAuth - Step-by-Step Instructions (Click ⏷)

Note: The Jira - Connection page defaults to the OAuth authentication method

  • Enter a Connection Name // Friendly name or alias for the connection

  • Enter the Instance URL // URL to the instance of Jira we are connecting to

  • Click Connect to Jira

    Jira Connection - Enter the Instance URL and click Connect to Jira

Setup OAuth

Jira ALM Connection Setup OAuth Modal

The Setup OAuth window will pop up (see below). Before we click any button on this popup modal we need to setup an Application Link in Jira to make the OAuth connection.

Follow the steps mentioned in the embedded video linked here (and embedded below), OR follow the step-by-step written instructions below.

Written instructions to complete the OAuth Setup / Jira Application Link and WebHook

Prerequisite: In a separate browser tab be logged into Jira with a [Service] User account that has Jira Admin privileges.

Note: this does not need to be the Jira Service User account that can be used to authenticate but if it is different you need to first set up the Jira Application Link with the Jira Admin user and then log out/login as the Jira Service User that will be used to authenticate the ALM Connection.

We now need to create the Jira Application Link:

  1. Click Settings > Jira admin settings > Jira apps

    Jira Administration Settings > Jira apps

  2. Navigate to Integrations menu section on the left-side panel

    1. > Click Application links

      Jira apps > Integrations > Application links

  3. Click Create link button in the top right of the Application links page

    Jira Application Links > Create link button...

On the Create an application link screen > Application link type > Connection type*

  1. IMPORTANT: Click the Direct application link using OAuth 1.0 radio button

  2. Enter https://piplanning.io in the Application URL* field

  3. Click Next

In the newly opened popup window titled Configure Application URL

  • Click Continue

A new screen will appear asking for additional required fields to complete the application link set up:

  1. Enter an Application Name: a string alias for example piplanning_io

  2. IMPORTANT: Scroll to the bottom of the form, and click the checkbox labeled Create incoming link

  3. Click Continue

Now, return to the RTE Cockpit

The OAuth dance starts. We alternate between the browser tabs for Jira and the piplanning.io RTE Cockpit.

  1. Return to the RTE Cockpit > Setup OAuth screen

    1. Copy the Consumer Key from the RTE Cockpit > Setup OAuth screen

  2. Return back to Jira on the Review link modal

    1. Enter the copied Consumer Key in the Consumer Key* field

    2. Enter a Consumer Name value can be an alias or friendly value. We suggest naming it piplanning.io.

  3. Return back to the RTE Cockpit > Setup OAuth screen

    1. Copy the Public Key from the RTE Cockpit > Setup OAuth screen

  4. Return back to the Jira Review link screen

    1. Enter the copied Public Key into the Public Key* field

    2. Click Continue

  5. Return to the RTE Cockpit, to click Authenticate in the Setup OAuth modal.

    1. Click Authenticate

  6. A new browser tab will open for Jira to to finalize the OAuth authentication. Follow the steps displayed on the new Jira page (screenshot below).

    1. Click Allow and the page will redirect.

    2. Close the Welcome to JIRA browser tab.

  7. Navigate back to the RTE Cockpit

    1. Click Check & Close on the setup page in piplanning.io.

Troubleshooting Jira Software OAuth Setup

If you see an error when you click Authenticate:

Open the Dev Tools / JavaScript Console in your browser and check for additional errors.

  • Check for an error like: oauth_problem=signature_invalid

  • IF connecting to Jira Data Center, then make sure that your Jira Data Center instance is properly configured in terms of its Base URL.

    • Jira Data Center: If you use a network proxy or gateway to access Jira, OAuth may not work. Please contact us through the In-App Messenger or write to [email protected].

    • Jira Data Center: The Base URL configured in Jira (System Settings) and in the <JIRA-INSTALL>/conf/server.xml file must exactly match the URL you have entered to connect to Jira in the RTE Cockpit.

  • Additional information can be found on the Atlassian help page: https://confluence.atlassian.com/kb/oauth-error-oauth_problem-signature_invalid-720406720.html

Basic Auth - Step-by-Step Instructions (Click ⏷)

Prerequisites: You need to be logged into Jira (in a separate browser tab) with the recommended Service User account or a Jira User account that has the appropriate permissions.

  1. Click the link Switch to Basic Auth

  2. Add a Connection Name // Friendly name or alias for the connection

  3. Add the Jira Instance URL // URL to the instance of Jira we are connecting to

  4. Add the Jira Users Username and Password

    • For Jira Cloud the value to enter into the Password field is an API Token for that Username. See below.

    • For Jira Data Center the value to enter in the Password field is the Users local Password.

Note: IF want to connect to Jira Cloud - using Basic Auth. - you must generate an API Token for the Jira Service User account that will be used to complete the authentication. You will need to generate an Atlassian Account (Jira Service User) API Token to enter into the Password field for Basic Auth. Please go here to learn more: https://id.atlassian.com/manage-profile/security/api-tokens. For ALM Connections to Jira Cloud the OAuth method is advised.

Re-Authenticate (Reconnect with Service User account)

Have you set up the Jira ALM Connection using your personal Jira User account, and now want to authenticate with a Jira Service User account?

Click the button below and follow the steps in the video to re-authenticate with a new (Jira) Service User account. The redirect to the video may take 2-3 seconds to load.

Reauthenticating to Jira Software with a Jira Service User Account

Connect to a Jira instance that has an Unsigned Certificate

You can deactivate the TLS / SSL certificate check in the Advanced Settings page of the ALM configuration.

  • Check the Advanced Settings checkbox on the #1 Connection tab.

  • Uncheck the Verify TLS / SSL certificates

REMINDER!

The Jira Service User account that you use when setting up the ALM Connection will be used to perform all the basic operations - Create, Read, Update, Delete / CRUD - in the real-time sync between Jira (Cloud or Data Center) and piplanning.io.

Please make sure that this User has appropriate permissions: Create/Update Work Items in the required Jira Projects, Delete (optional), and the ability to Read the Jira Project metadata (Workflows and Status), manage Jira Sprints etc.

Related Articles
Jira Team Mapping
piplanning.io attributes <> Jira fields
Adding a Webhook to Jira
Jira Software ALM Connection: Discovery + Setup Preparation
Kanban Teams | Jira Kanban Boards
Did this answer your question?