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.
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.
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)
|
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:
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
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
Ping One SAML 2.0 Setup for Jira Align
Was this helpful?
Thanks!
Chris Jeggo
12 comments