Troubleshoot Connections
Are you having issues connecting your Jira instance with the app? Most likely, your network is preventing you from connecting the Playbook for Jira app to your Jira instance. But we can help fix that!
If your Jira Server instance doesn't have a firewall or is open to the public, you can ignore this topic. All of the advice and recommendations discussed on this page relate to issues surrounding secure instances.
Playbook for Jira begins the configuration process by pinging the [URL_YOU_ENTERED]/plugins/servlet/oauth/request-token in Step 1 of the Configure New Instance modal to confirm that the URL is valid and that the app can successfully retrieve a request token. If you receive error messages during this process, here are a few common explanations:
- Your Jira instance requires individuals (incoming connections) to authenticate via an SSO portal before access
- Jira is behind a proxy that redirects and validates network traffic, causing timeouts
- You have multiple DC nodes with variable settings, which can cause some calls to the application to fail while others are unaffected, depending on which node handles the request
Listed below are notes on these common issues, including steps you can take to resolve them.
Allowlist the IP address
First things first.
Allowlist the Playbook for Jira static IP address so it can pass through your firewall and establish connections with Jira.
The IP address for the Playbook for Jira app is 52.202.15.17.
You only need to permit incoming connections from the app.
Allowlist URLs
If you suspect an issue related to your network configuration, take a look at Atlassian's tips, paying specific attention to the information in the Workaround section. Chances are that you haven't allowed the URLs to bypass SSO authentication.
Per Atlassian's advice, ensure that you've allowlisted each of the following URLs:
/plugins/servlet/oauth/authorize/plugins/servlet/oauth/access-token/plugins/servlet/oauth/request-token/plugins/servlet/oauth/consumer-info/plugins/servlet/streams/plugins/servlet/applinks/whoami/rest
Allowlisting these URLS permisses Playbook for Jira, calling from its static IP address, to bypass SSO authentication to talk to and authenticate directly with the Jira instance via OAuth. Some of the URLs allow for authentication to happen over the OAuth standard and are only for establishing and negotiating valid authentication tokens. The other endpoints, such as /rest (which the app uses to get, store, and update information in Jira), are for API access to Jira. All of these endpoints are secured by Jira and will block all requests that don't contain a valid OAuth authentication token.
You cannot use the app without allowing these URLs to bypass your SSO authentication.
This requirement does not increase the vulnerability of your Jira instance's security thanks to the app's use of OAuth 1.0, which assumes the security responsibility to only allow our app to receive and pass only the information it needs to work. Your Jira instance will not be open and vulnerable to other apps or programs.
Timeout errors
Do you have a proxy setup for your Jira instance? Do you have multiple nodes on your Jira DC instance?
If you answered yes to either of these questions, some necessary URLs may be taking too long to access given that Slack has a limit for request/response interactions. If network rerouting (via proxies, nodes, etc.) takes more time than Slack allows, you may experience that the app fails to call dynamic assets like your Jira project list.
To avoid this issue, Playbook for Jira needs unhindered access to the aforementioned endpoints during the application-link setup and OAuth process. If your network team is unable to allow access to those URLs for Playbook for Jira, then it will not be possible to use the app.
App-link issues: Advice from Atlassian
The Playbook for Jira application authenticates Jira Server/DC users via OAuth 1.0.
If you experience issues setting up an app link, see Atlassian's application-link troubleshooting guide for more information.