What this article covers:
- How to use the ngrok secure tunnel to securely expose Jira to Unito
- On-premise domain validation
Warning: every time you run ngrok, you will get a new forwarding URL, which will cut off Unito's access to your Jira server. We recommend you use an ngrok custom subdomain.
This guide is intended for customers running an on-premise Jira server 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 this article.
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.
3) Add a connector to Jira's server.xml
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 your Jira server 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 your Jira server. You can now create new workflows with your Jira server!
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.
Reference documentation for Jira and ngrok are also available.
On-premise URL domain validation
With on-premise tools, security is doubly important. That's why when you add the domain for your server, we'll check if it matches one of your email addresses — or another verified domain. If it doesn't, you'll probably get this error.
This error could pop up when using ngrok. If you get this error, please reach out to us so we can resolve the issue.