How to Use ngrok to Connect an On-Premise Jira Server or Data Center

If you're running an on-premise Jira server or Jira Data Center that isn't reachable via public Internet, here's one way to connect to Unito.

What does this article cover?

Warning: every time you run ngrok, you will get a new forwarding URL, which will cut off Unito's access to your Jira Server or Data Center. We recommend you use an ngrok custom subdomain.

This guide is intended for customers running an on-premise Jira Server or Data Center that is not reachable over the public Internet. It describes one approach to securely expose Jira to the Unito service by leveraging the ngrok secure tunnel. There are also other options described in Unito’s Full Guide to On-Premise Installations.

1) Download and run the ngrok client

Download the ngrok client for your platform, and copy it to the server running your Jira application.

Find out which port your Jira is listening to. By default this is port 8080, and you can test it by opening http://localhost:8080 in a browser or using curl on the command line, both directly from the Jira server.

Start the ngrok client on that port:

$ ngrok http 8080

2) Test the tunnel

ngrok will show you a Tunnel Status and indicate an HTTPS URL.

Paste that URL in a browser. Make sure you use the HTTPS URL, not the unsecure HTTP one. You should see Jira load up.

Scroll to the bottom, you will likely see this warning from Jira . If you don't get any warning, you can skip to the last step below.

Note: If you experience an error displaying the message: 'Web Page blocked!', it could potentially be the result of your organization's imposed limitations on accessing particular online domains.

3) Add a connector to Jira's server.xml file

Open the server.xml configuration file for your Jira application. By default, you'll find it under the conf/ folder of your Jira installation.

Find the element under the <Service> section. You'll want to add a new element as such:

The important part here is scheme="https", which tells Jira you're going through a service (ngrok) that invisibly adds HTTPS over Jira's connection.

Note, we used port="8081", but you can choose any other port. Just remember to use that port when you next run ngrok.

4) Restart Jira and ngrok

Restart your Jira server and the ngrok client, this time with the new port number:

$ ngrok http 8081

Now, if you access the new ngrok HTTPS URL in your browser, you should no longer see the warning.

5) Connect Jira Server or Data Center to Unito

In the Unito app, add a new Jira account. When prompted, paste the ngrok forwarding URL. You should then be prompted to login/authorize by Jira Server or Data Center. You can now create new flows with Jira!

If you're still having trouble or would like a more advanced network configuration, please reach out to us and we'll figure out the right setup with you.

Note: don't forget to create your Jira application link.

Bonus: for stricter security, you can use ngrok's IP whitelisting feature to limit access to only Unito's fixed IP addresses.

Reference documentation for Jira and ngrok are also available.