Application links are the connections that support most of the integrations between Atlassian server applications. Read more about using your Atlassian tools together at Streamline software development with Atlassian tools.

If you're just wanting to set up an application link see Link Atlassian applications to work together.

Jump to...


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 your application links have stopped working after a recent upgrade it's possible that your customizations to the application's server.xml file were overwritten. Custom changes can include reverse proxy configuration and HTTPS configuration. You should check that the upgraded server.xml file matches the pre-upgrade server.xml.

The location of your server.xml file depends on your application, operating system, and installation location. 

Common default installation locations for Atlassian applications are:

  • Linux: /opt/atlassian/<application-name>
  • Windows: C:\Program Files\Atlassian\<application-name>
  • Windows: C:\Atlassian\<application-name>

Locations in Atlassian application's folder structure:

Applicationserver.xml location
Bamboo<install-path>/conf/
Confluence<install-path>/conf/
Crowd<install-path>/apache-tomcat/conf/
CrucibleAs for Fisheye.
FisheyeThe Fisheye configuration file is config.xml, see Configuring the Fisheye web server and How to enable Fisheye/Crucible to listen to web requests on additional ports.
JIRA applications<install-path>/conf/
Bitbucket Server 5.0

N/A, replaced by <Bitbucket home directory>/shared/bitbucket.properties

Please read through Migrate server.xml customizations to bitbucket.properties

Bitbucket Server 4.0 – 4.14<Bitbucket home directory> /shared/server.xml
Stash 3.8 – 3.11

<Stash home directory>/shared/

If you are on any of these later releases but your server.xml does not exist in the directory above, it means that you are running from the <install-path>/conf/server.xml.

We recommend that you copy <install-path>/conf/server.xml into <Stash home directory>/shared/ that way you won't need to worry about this when you upgrade your instance.


Stash 3.7 and earlier<install-path>/conf/

<install-path> refers to where the application was installed on your system.


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:

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.

Refer to our SSL and application link troubleshooting guide for detailed information about how to diagnose and fix SSL problems with application links.

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.

Logging configurationApplication logsTomcat webserver logs
Bamboo <Bamboo installation directory> /logs  
Bitbucket Server / Stash

<Bitbucket home directory>/log

<Stash home directory>/log

<Bitbucket Server installation directory>/logs

<Stash installation directory>/logs

Confluence <Confluence home directory>/logs <Confluence installation directory >/logs
Crowd <Crowd home directory>/logs <Crowd installation directory>/apache-tomcat/logs
Crucible <Crucible installation  directory>/var/log/  
Fisheye <FishEye installation  directory>/var/log/  
JIRA applications <JIRA application home directory>/log <JIRA application installation directory>/logs

Consider enabling the DEBUG level of logging on the application to get more detailed logs – DEBUG adds all stack traces, and includes HTTP response messages.

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

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

Note: Deleting or modifying an application link is a non-destructive process. Any existing macros or gadgets will resume functioning once the link has been recreated correctly. No content is removed as a result of removing an application link.

However, note that:

  • Deleting then recreating an application link will force all of your users to log in again.
  • If your instance has Project Links defined, these will be deleted along with the application link. They must be recreated after the application link has been recreated.

See Delete an application link for instructions.

See Link Atlassian applications to work together for instructions.


The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following network and connection problems that can occur with application links:

Follow the links above for diagnostics and specific actions you can take to resolve these connection problems.

Otherwise, see our Network and connectivity troubleshooting guide for general solutions or see the error messages related to network and connection problems.


The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following OAuth problems that can occur with application links:

Follow the links above for diagnostics and specific actions you can take to resolve these OAuth problems.

Otherwise, see our OAuth troubleshooting guide for general solutions or see the error messages related to OAuth problems.


The 'Configure Application Links' screen in Atlassian products provides diagnostics for the following SSL problems that can occur with application links:

Follow the links above for diagnostics and specific actions you can take to resolve these SSL problems.

Otherwise, see our SSL and application link troubleshooting guide for general solutions or see the error messages related to SSL problems.

Creating an application link between a site and its clone (a Jira site exported from the source site and then imported onto a second site) is not supported.

Workarounds:


  • No labels
 




 

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.