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

Note: Jira Align will need to be able to connect (GET/POST) to this Jira URL for OAuth 1.0a setup: "/plugins/servlet/oauth/*"

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

Connecting Jira Align to Jira Data Center with Apigee as a 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, ask your CSM or SA to obtain it for you.

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

Apigee

Mulesoft API Manager

Connecting Jira Align to Jira Data Center with Apigee as a Reverse Proxy 

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

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}

 

Additional API Resources

Jira and Jira Align Integration: Jira Rest API Calls for Configuration and Troubleshooting 

 

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.

Additional SSO Resources

Jira Align SAML 2.0 Setup 

Ping One SAML 2.0 Setup for Jira Align 

Azure Active Directory SAML 2.0 Setup for Jira Align 

Okta SAML 2.0 Setup for Jira Align 

12 comments

Richard Wilson _Jarow Digital_ January 28, 2020

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

Like Tim Keyes likes this
Mark Cruth
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 28, 2020

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

Like Tim Keyes likes this
Shawn Kessler
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 28, 2020

Well done, @Chris Jeggo !

Arden_Hawley January 28, 2020

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
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
January 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
Atlassian Team members are employees working across the company in a wide variety of roles.
January 28, 2020

@Chris Jeggo this is awesome!

Like # people like this
Peggy Graham
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 28, 2020

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

Like # people like this
Tim Keyes
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 28, 2020

@Chris Jeggo  Excellent work and thank you for posting!

Like # people like this
Emily Koch
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
January 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
Atlassian Team members are employees working across the company in a wide variety of roles.
February 4, 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
Atlassian Team members are employees working across the company in a wide variety of roles.
August 5, 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.

Bryan Smith
Atlassian Team
Atlassian Team members are employees working across the company in a wide variety of roles.
December 13, 2023

This article is great... but it's a few years old. Is there an updated one? Or is all/most of the info still as relevant today as it was then? Thanks! Bryan

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events