Jira Align Cloud to Jira Cloud Connectivity - Quick Guide

[#1]

Purpose

This article is designed to get Jira Align to Jira Cloud connectivity up and going quickly.

Looking for the Jira Data Center guide, rather than Cloud? We've got you covered, here it is.

---

Prerequisites:

• You have access to Jira Align as a Super Admin. 
• You have configured and have access to the Service Account in Jira. 
• You have access to Jira Cloud as an Admin.  Note: Site Admins do not always automatically have access to the Jira Software Products. Double check that you are a member of a group that has access to the product. See admin.atlassian.com > Directory > Groups
• For Premium Jira Cloud Accounts, you have allowed Jira Align access through IP Allowlisting (only if this feature is currently being used).

A note about OAuth vs Basic Auth. It is at Jira Align's recommendation that you use OAuth 1.0a for authentication between Jira Align to Jira Cloud.  Authenticating with the Atlassian API Token is fine, however the API Token in question is tied to the Atlassian account while OAuth is tied specifically to the application link in Jira Cloud.

If you opt to use Basic Auth instead of OAuth, just flip the Authentication Type in Step 4 to Basic Auth, enter the Service Account's email address in the Jira Username field, and the Service Account's Atlassian API Token in the API Token/Jira Password field. Skip all the way down to Step 21.

Note: For step 1 in the linked 'Atlassian API Token' guide, you must log into the site as the Service Account. This may require a non-cached browser session if existing credentials are already cached.

For more information on Authentication Methods, see this article.

---

Connector Setup in Jira Align

1) In Jira Align, click on the Administration Gear in the bottom left.

2) Click on Connectors > Jira Settings in the second column.

3) Click on the Jira Connectors button in the main pane.

4) Fill out the Jira Connector as follows:

• Jira Link: https://__.atlassian.net/browse/{external}
• Name: Anything descriptive. This is a vanity name only.
• Admins: Add any other Jira Align users that you want to manage this connector that are not Super Admins.
• Jira API URL: https://__.atlassian.net
• Authentication Type: OAuth 1.0 Authentication (highly recommended)
• Jira OAuth Consumer Key: Anything descriptive. Remember this Consumer Key for later.
  • Note: Do not use spaces or symbols for the Consumer Key!

Additional Note: If the Service Light is gray and not green, then you'll need to contact  Jira Align Support  to activate the service before proceeding.

5) Once the above has been filled out, click Generate New Key and copy it to your clipboard.

• Note: Some browsers have issues copying this block of characters so you may have to try a few times to get it in the clipboard. I've also found resizing the text box and then copying helps as well.

6) Click Save at the bottom of the Connector window.

7) Login to Jira, click the Settings cog in the top right, and select Products.

Note: Alternatively, you can click on any whitespace in Jira and press "." and search for Application Links. 

 

8) On the left column, under Integrations, click Application Links.

9) Enter the Jira Align URL (https://__.jiraalign.com) in the field and click Create New Link.

10) Jira Cloud may complain there was no response. Just click Continue.

11) Fill out the Application Name with something descriptive.

12) Click the Pencil to edit the newest application.

13) Go to Incoming Authentication and fill out the Consumer Key with the same one used in Step 4. 

 

14) Paste the OAuth Public Key you copied from Step 5. 

15) Scroll down and click Save.

16) Go back to the Jira Align Connector window from step 4.  

17) Click Authorize Jira OAuth access.

Note 1: If a Jira OAuth token authorization already exists, the button will display as Reauthorize Jira OAuth access. Clicking this will perform the same process of generating a fresh OAuth token.

Note 2: You will see this request go through 3 steps and will refresh several times. It will take a few minutes for this process to complete.

Note 3: If you are having trouble with this step, make sure that the Consumer Key matches on both sides and contains no spaces or symbols.

In addition, check that the OAuth Public Key are an exact match on both sides.

Lastly, make sure that the Application URL configured in the Jira Application Link is correct without any typos.

Note: For the next step (18) make sure you are logged into Jira Server/Data Center as the Jira Service Account in another tab of the same browser. The Jira Align connection to Jira Software will use whichever account you were signed in as. If you are signed in using your personal account, that means your name will be written on any updates pushed from Jira Align to Jira Software, instead of the name of the Service Account you created.

18) Once the OAuth access setup has completed, click Request Jira for access.

19) You'll be taken to another tab asking you to allow the application to have access. Click Allow.

20) The connector screen will now show Reauthorize Jira OAuth access (instead of Authorize Jira OAuth Access, or Request for Jira Access). This is how OAuth in Jira Align will look when the process is completed:

21) Click Save on the bottom of the Connector window.

22) (Skip this step if you used OAuth as the authentication method instead of Basic Auth.) One final test to confirm connectivity is the Test Now button at the bottom of the Jira Connector window. You may need to scroll down to see it.

Note: This test doesn't automatically refresh so you'll need to close and reopen the connector window periodically. This test also takes a few minutes to complete.

Note: If the test fails, this may not be a blocker. Please work with Jira Align Support if there's any questions around the Test Now button.

23) Click Activate on the bottom of the Connector window. (If it is not already activated. If the button says "Deactivate," you can skip.)

24) Now that you are connected, you can sync a test project. 

Additional related articles:

10X Jira Integration Setup 

NOTE: For any of the authentication methods (OAuth, PAT, API Authentication/Basic Auth), if you need to change them (i.e. expired token or password), you'll need to Deactivate the connector, make the authentication update, save, and then Activate the connector. 

[Hina Tufail]

Hi @James McCulley ,

I see this article is from 2020. I have a question that might be interesting to integrate in this current article : Article on the URL update on Jira Cloud 

This article is from the 6th August 2021 and this is a new feature.

What happens if the customer changes his Atlassian URL ? Does Jira Align automatically gets it without any update or is an update required with the following fields : Jira Link and Jira API URL ?

Is it something that can be done autonomously or do the customer need to reach the support ? If yes, before or after the URL change in Jira Software Cloud ?

This question might be interesting for several users so that's why I chose first to comment on here.

Thanks :)

[James McCulley]

Hello @Hina Tufail

Thank you for the suggestion as I hadn't seen this feature yet.

My initial testing and subsequent findings have resulted in the following recommendation:

You'll need to update the Jira Link and Jira API URL  in the Jira Align Connector immediately after updating the Jira Cloud Product URL and confirming the new Jira Cloud Product URL is up and running. Keep in mind that there will be a period of time (5 minutes per the documentation) while the Jira Cloud Product URL is updating from old to new where Jira Align may not be able to connect to Jira Cloud. 

Thanks!

James

[Hina Tufail]

@James McCulley Thank you !