Skip to main content

Creating the ALM Connection to Jira

How To connect piplanning.io with Jira Software (Cloud or Data Center). All the administrative tasks for OAuth or Basic Authentication.

Updated today

Step #1: Create a Service User account in Jira

We strongly recommended a Service User account in Jira - with the required CRUD permissions for Jira Projects - to authenticate the ALM Connection.

Note: Make sure that 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 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:

  • BROWSE_PROJECT

  • CREATE_ISSUES

  • DELETE_ISSUES (optional)

  • EDIT_ISSUES

  • LINK_ISSUES

  • SCHEDULE_ISSUES

  • MANAGE_SPRINTS_PERMISSION (optional)

  • MODIFY_REPORTER

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 the OAuth* authentication method continue here.

    IF you wish to use the Basic Auth authentication method continue here.

*Note: 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 Authentication - Step-by-Step Instructions

  1. On the Jira - Connection page it defaults to the OAuth authentication method

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

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

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

  2. Click Connect to Jira //The Jira OAuth authentication dance starts

  3. This 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 inserted below), or follow the step-by-step written instructions below.

Written Instructions to complete the OAuth setup

Prerequisite: In a separate browser tab be logged into Jira with the Service User account we recommend for the integration.

Navigate to the browser tab where you are logged into Jira with the Jira Service Account and with Administrator privileges. We now need to create an Application Link:

  1. Click Settings > Product > Jira apps

    Jira Administration Settings > Jira apps

  2. Navigate to Integrations on the left-side panel menu > Click Application links

    Jira apps > Integrations > Application links

  3. Click Create link button

    Jira Application Links > Create link button...

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

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

  • Enter an Application Name: a string alias for example piplanning_io

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

  • Click Continue

Now return to the RTE Cockpit. The OAuth dance starts. We alternate between Jira and RTE Cockpit browser tabs.

  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

Now, return back to the RTE Cockpit, to click Authenticate in the Setup OAuth modal.

  • Click Authenticate

A new browser tab will open for Jira to to finalize the OAuth authentication. Follow the steps displayed on the new Jira page:

  • Click Allow and the page will redirect. Close that Jira browser tab.

Navigate back to the RTE Cockpit

  • 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 Browser Dev Tools / JavaScript Console in your browser and check for additional errors.

  • Check for an error like: "oauth_problem=signature_invalid":

  • Make sure that your Jira Data Center instance is properly configured in terms of its Base URL.

    • If you use a proxy to let the piplanning.io access your Jira, OAuth may not work. Contact Us through the In-App Messenger or write to [email protected].

  • 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 Authentication (Basic Auth) - Step-by-Step Instructions

Prerequisites: You are logged into Jira - Data Center or Cloud - 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 reauthenticate with a Jira Service User accont?

Click the button below and follow the steps in the video to re-authenticate with a new (Jira) Service User account.

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) 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?