It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Jira Align & Jira Connectivity

One of the bigger challenges of a successful Jira Align implementation is getting Jira Align connected to a Jira instance that is located behind a firewall. The aim of this article is to give new clients an idea of what may be involved (as it will vary depending on your network architecture) and existing clients a refresher in case of migrations or network changes that will inevitably happen over time. Although it will not cover the finer details, it should serve as an overview of the task at hand and provide a way to test connectivity before implementing Jira Align, therefore saving some time when the site is set up and ready to connect. If you are using Jira Cloud or your Jira is fully accessible to the world already, you are done and can skip this. 

You may not need to do every section in this article. How much you need to do is dependant on your infrastructure and company policies.

Although the below diagram a huge oversimplification of a network architecture, it illustrates the end goal - expose the Jira API to the edge of the network so Jira Align can communicate with it.

SuperSimpleDMZ.png

How this is achieved will vary depending on the environment, but generally, we are talking about one or a combination of three options after Jira has been configured:

  • Opening firewall ports/whitelisting
  • Reverse proxy and/or API gateway
  • On-prem agent

These are the four API-based URLs that the Jira connector requires:

  • /rest/auth/
  • /rest/api/2/
  • /rest/agile/1.0/
  • /rest/greenhopper/1.0/

The verbs needed for each of those are:

  • GET /rest/** 
  • POST /rest/**
  • DELETE /rest/**
  • PUT /rest/**

Where ** = the endpoints listed above i.e. /auth

 

Which technical teams need to be involved?

This is a non-exhaustive list of the typical people involved in connectivity projects. Role names may differ between organizations. It can help to have a network diagram to hand and trace the route that data will have to take to get from Jira to the edge of the network, then involve whoever owns each piece.

Teams.png

 

Proxy Configuration

If you need to get Jira through a proxy, please see these guides for reference that were produced by the Jira Server teams:

Configure an outbound proxy for use with Jira

Integrating Jira with Apache using SSL

Configure Jira to run behind an NGINX reverse proxy

Troubleshooting

Most common failures can be addressed using the Jira Troubleshooting Articles for Application Links documentation.

Although Atlassian does not support proxy configuration, Jira Support may also be able to provide further guidance in some circumstances. 

 

Certificates

For the purposes of prep work and testing, this can section can be skipped. This is here so that the potential impact to your configuration can be seen upfront.

Wildcard Certificate

To obtain the certificate, navigate to an existing Jira Align instance or ask your CSM or SA to obtain it for you. Simply click on the padlock icon in Chrome, Certificate then in the Details tab of the dialog, click the copy to file button.

Wildcard1.pngWildcard2.png 

The Certificate Export Wizard should now open. Follow through the steps and save the certificate file in the format required by your infrastructure. 

Customer Provided Certificate

Once the site is set up and ready (CSM or SA will confirm), open a ticket with Jira Align Support to initiate certificate exchange with the Jira Align Operations team

Jira Align Issued Certificate

This should be declared as part of the sales process. When ready, open a ticket with Jira Align Support for certificate exchange. 

 

Firewall Configuration

Depending on the type of firewall you have, you may have the ability to provide greater restrictions as required by your organization. How the restrictions are implemented will differ between firewall vendors. Atlassian does not provide support for the configuration of firewalls so below is just an idea of what you may need to configure.

For pre-sales testing purposes, this is here for the reference of future work to be completed as there will not be a Jira Align site set up for you so there is no need to make the changes just yet.

IP Whitelisting

When purchasing Jira Align, you will be given the option of where your instance is located but by default, we put them as close to you as possible. The AWS regions used are:

AWS Region        Region Name

us-east-2

US East (Ohio)

eu-central-1 Europe (Frankfurt)
ap-southeast-2 Asia Pacific (Sydney)

Your point of contact in the sales process or Jira Align Support can provide the required IP addresses when needed.  

Ports

The Jira Align connector service uses SSL/TLS for all communications over port 443.

Domains

If your firewall supports or requires names, either of the below depending on your configuration:

*.jiraalign.com
<your_site_name>.jiraalign.com

Configuration Resources

Some vendors provide their documentation on a per license basis via a user portal, so if you have that, please refer to the official docs. Here are some links to some of the more popular solutions and how to configure them:

Cisco ASA Whitelisting (video)

Juniper SRX

Barracuda NextGen

Fortinet Fortigate

F5 BIG-IP

 

NOTE: We have covered firewalls here, but there may be additional configuration required for other security appliances such as intrusion detection/protection devices, for example, McAfee IPS or F-Secure. Please consult with your Network/Security Admins for assistance with these devices.

 

API Gateway Configuration

If you are using or plan to use an API gateway, please refer to the gateway vendor's documentation or support (links below to get started). Typical API Gateways we see include:

NGINX as an API Gateway

Kong API Gateways

Apigeee

Mulesoft API Manager

The endpoints required are listed above but how each is configured will depend on the gateway vendor.

 

On-prem Agent

Things like ngrok link.

Untested and you are at the mercy of 3rd party software being installed on a Jira server....

Technically possible if all else fails but Atlassian support cannot assist with this.

 

Testing Connectivity

Testing the API from the internal network can give false positives depending on how the network is set up - for example, you may not be hitting the external endpoint you exposed if you test internally. To avoid this, either hook up to a mobile hotspot or a corporate guest network for testing purposes. The aim is to simulate an external client hitting the API endpoint.

We DO NOT recommend using online/hosted API testing tools. You will need to supply authentication credentials which comes with the risk of giving those to a 3rd party entity, so if you do this, you do so at your own risk.

For examples of Jira API calls to test with, please refer to Jira Rest API Examples Documentation.

JiraAlign requires GET, POST, DELETE and PUT verbs to be working. For testing, you can set up a testing project in Jira to fire calls against or use an existing one but be aware the calls may make changes to the item being interacted with depending on what call you are testing. 

Examples using cURL

If there are difficulties with hitting these endpoints, please consult with Jira Support/Community

There are many ways to do this, but cURL is probably the easiest and you could even script it. The basic syntax will be:

curl -u {jiraUsername}:{jiraPassword} -I -X GET {jiraURL:port}/{API_endPoint}

We advise creating a test account in Jira for tracking purposes, or even better, run your tests against your staging environment if possible. 

-u = Jira username and password separated by a colon. 

-I = Only show the HTTP response rather than the full JSON response

-X GET|POST|DELETE|PUT = Specify the request type

jiraURL:port = URL and the port number of the Jira instance

API_endPoint = Endpoint you want to test

Expected response

ResponseCodes.png

HTTP/1.1 200 X-AREQUESTID: 636x513x1 
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
Content-Security-Policy: frame-ancestors 'self'
X-ASEN: xxxx
Set-Cookie: JSESSIONID=xxxxxxxxxxxx; Path=/; HttpOnly
X-Seraph-LoginReason: OK
Set-Cookie: xxxxxxxxxxxxxxxxxxxxxxxxxx; Path=/
X-ASESSIONID: 1pry94l
X-AUSERNAME: xxxxxx
Cache-Control: no-cache, no-store, no-transform
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: xxxxxx

Example API Calls

Please review the Jira API docs provided. The GET examples are safe but anything else will modify data if sent correctly! For that reason, the full cURL command has not been provided, just the first part of it. There are many ways to do this, those listed are just example possibilities.

GET

curl -u {jiraUsername}:{jiraPassword} -I -X GET {jiraURL:port}/rest/auth/latest/session/ 

curl -u {jiraUsername}:{jiraPassword} -I -X GET {jiraURL:port}/rest/api/2/issue/{optional_IssueID}/

curl -u {jiraUsername}:{jiraPassword} -I -X GET {jiraURL:port}/rest/agile/1.0/board/{board_ID}/

curl -u {jiraUsername}:{jiraPassword} -I -X GET {jiraURL:port}/rest/greenhopper/1.0/rapidview/

 

POST

curl -u {jiraUsername}:{jiraPassword} -I -X POST {jiraURL:port}/rest/greenhopper/1.0/sprint/{rapidviewID}/ 

 

DELETE

curl -u {jiraUsername}:{jiraPassword} -X DELETE {jiraURL:port}/rest/greenhopper/1.0/rapidview/{rapidviewID}/

 

PUT

curl -u {jiraUsername}:{jiraPassword} -I -X PUT <jira_url>/rest/greenhopper/1.0/sprint/{sprintId}

 

Setting Up SSO

The final piece that is not really connectivity related but might be of interest is SSO. Jira Align works with many SSO providers. Please take a look at this video for details.

11 comments

@Chris Jeggo , thanks for sharing.  Really appreciated and can be very challenging to get right. 

Like Tim Keyes likes this
Mark Cruth Atlassian Team Jan 28, 2020

Solid article on connectivity! This will help a TON of clients!

Like Tim Keyes likes this

Well done, @Chris Jeggo !

Put so simply, but at big companies this can take a lot of time to get right.  I finally just got our connector working in a similar architecture working and I'm glad people trying now have a good guideline out there now ;) 

Like # people like this
Peter Jessen Community Leader Jan 28, 2020

Wow! It's finally documented! So great to have this article to point clients to now for a detailed explanation. Thanks @Chris Jeggo.

Like # people like this
Sam Tsubota Atlassian Team Jan 28, 2020

@Chris Jeggo this is awesome!

Like # people like this
Peggy Graham Atlassian Team Jan 28, 2020

Thank you for this @Chris Jeggo !!  Sharing it now!  :-)

Like # people like this
Tim Keyes Atlassian Team Jan 28, 2020

@Chris Jeggo  Excellent work and thank you for posting!

Like # people like this
Emily Koch Atlassian Team Jan 30, 2020

Thanks for posting this, Chris! Connectivity seems to be one of the most commonly encountered obstacles in getting the connector up and running, so this definitely will help to troubleshoot if those difficulties arise.

Like # people like this
Rich Sparks Atlassian Team Feb 04, 2020

Hey @Chris Jeggo thanks for this excellent writeup. I'm sharing this with a few of my colleagues so they can help their enterprises get prepared and make sure they have the right people (with the right knowledge) involved in the setup.

Like # people like this
Tarun Sapra Atlassian Team Aug 05, 2020

Important info 

The jiraalign.com domain will become available on Friday Night July 31st and will be simultaneously supported with your existing agilecraft.com domain until October 16th, at which point the agilecraft.com domain will be retired.

Comment

Log in or Sign up to comment
TAGS
Community showcase
Published in Jira Align

Virtual/Remote PI Planning Best Practices and FAQ Table of Contents

Due to recent challenges of most companies having to move to virtual and remote PI planning events, the Jira Align Solutions Architects wanted to start to capture some best practices and FAQ Table of...

3,578 views 3 31
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you