Application Links Troubleshooting Guide

If you've changed your environment, such as reverse proxies, physical servers or even URLs, it's best to recreate the link just in case. Recreating an application link doesn't remove any data. Existing macros, plugins and pages that make use of an application link will start working again once the application link has been recreated.

Note however that recreating the link will force all of your users to log in again.

If an application involved in your application link is hosted on Atlassian Cloud, there are a couple of considerations. Your local server must use a valid SSL certificate, and it must be accessible on one of these ports: 80, 443, 7990, 8060, 8080, 8090, or 8443.

If you have a internet-facing firewall, make sure to allow the IP range used by Atlassian to reach your internal network. For up-to-date information on that, see Atlassian cloud IP ranges and domains. 

Full integration between Atlassian applications, such as Bitbucket Server and Jira Software, requires a reciprocal (two-way) application link between the applications.

Both ends of the application link should use the same authentication mode. Atlassian only recommends OAuth authentication.

To get full integration when creating the application link you must check the box marked Also create a link... back to this server, enter your administrator credentials for the remote application, and then select your user base scenario to configure authentication.

If you think you've already set up application links in both directions, you can check that as follows:

1. In the local application, go to Administration > Application Links and make sure there is an application link entry for your remote application.
2. In the remote application, go to Administration > Application Links and make sure there is an application link entry pointing back to your local application.

See our instructions for how to create an application link at Link Atlassian applications to work together.

If you local and remote applications are not able to communicate over the network you'll see NETWORK ERROR for the link on the Application Links Configuration page.

Refer to our Network and connectivity troubleshooting guide for detailed information about how to diagnose and fix connection problems.

The configuration of an application link depends on whether your network includes firewalls, reverse proxies, load-balancers or other network devices or services.

In particular, the application URL used for the application link must be the URL that you use to access the remote application.

Refer to these pages for more information:

• Common Application Link Layouts
• Reverse Proxy and Application Link Troubleshooting Guide

You should use OAuth authentication for your application link. Atlassian no longer recommends using Basic HTTP authentication or Trusted Applications authentication.

Furthermore, both ends of the application link should use the same authentication configuration.

OAuth authentication is set by default for newly created application links, but you can modify an existing application link to use OAuth.

To check: 

1. In the local application, click Administration > Application Links.
2. Click Edit for the application link. Check the OAuth setup on the Incoming Authentication and Outgoing Authentication tabs for your application link.
3. In the remote application, click Administration > Application Links.
4. Again, click Edit for the application link. Check the OAuth setup on the Incoming Authentication and Outgoing Authentication tabs for your application link. Check that the Outgoing Authentication tab setup matches the Incoming Authentication setup of the local application, and vice-versa.

Refer to our OAuth Troubleshooting Guide for detailed information about how to diagnose and fix OAuth problems.

This scenario occurs when the authentication used by the application link doesn't allow the two applications to fully trust each other. You can fix this by:

1. In the application that's prompting users to authenticate, change the Outgoing configuration setting for the application link to allow 2-Legged OAuth authentication.
2. In the application that users are trying to connect to, change the Incoming configuration setting for the application link to allow 2-Legged OAuth authentication.

See Link Atlassian applications to work together for more information.

Unsynchronized server times can break authentication.

• Is the time and date significantly different between each machine? Consider using a Network Time Server to ensure all machines are in synchronization.
• Is each machine aware of the time zone that it's in? Invalid time zones can cause problems during OAuth authentication.

Refer to our OAuth Troubleshooting Guide for detailed information.

2-Legged OAuth with Impersonation (2LOi) is recommended when you require an application to use impersonation (such as Jira Service Desk); or when you wish to avoid the confirmation prompts when accessing information across applications.

You should enable impersonation:

• When the user bases between each application are identical.
• When using applications that require impersonation, such as Jira Service Desk.

See OAuth security for application links for more information.

Atlassian server products are Java applications that bundle the Tomcat application server. Both the application and Tomcat generate logs that can help to diagnose a problem with application links.

You can use the error messages in the logs to find the relevant solution to your problem on one of these pages:

• Network and connectivity troubleshooting guide
• OAuth troubleshooting guide
• SSL and application link troubleshooting guide

Recreating the link ensures that the application link uses any configuration changes you've made while troubleshooting a problem.

Delete an existing link

See Delete an application link for instructions.

Create a new link

See Link Atlassian applications to work together for instructions.