Skip to end of metadata
Go to start of metadata

When you connect Atlassian applications using application links you get the security of the industry-standard OAuth authorization protocol. For a great introduction to how the OAuth authorization flow works, see this blog post.

To update an application link to use just OAuth, see Update application links to use OAuth.

If you want to create an application link between two Atlassian applications, see Link Atlassian applications to work together.

For version 5.2 and later, application links no longer support the Trusted Applications or Basic Access authentication types.

 

There are two OAuth security models that you can use with Atlassian application links:

 

OAuth authentication

OAuth with impersonation

Description
  • The user is redirected to log in to the remote application, after which tokens generated on their behalf are used to authorize requests made from the local application.
  • The remote application handling the request uses the access permissions of the account with which the user logged in on that remote application.
  • The local application makes requests on behalf of the user who is logged in to the application.
  • The remote application handling the request uses the access permissions of the account with which the user logged in on the local application.
Benefits
  • Can be used where the applications have different userbases (so a user can have different accounts on each application).
  • The user's credentials are never sent between applications, and so can only be compromised with difficulty.
  • Users see only the information that they have permission to see. 
  • Users don't need to authenticate when they request restricted resources from the remote application.
  • Users see only the information that they have permission to see. 
Requirements
  • A user has to authenticate on the remote application when first requesting restricted resources there (subsequent requests use the same token until the token expires).
  • The Development panel in the JIRA Software issue view only supports OAuth authentication.
  • Both applications must be Atlassian applications.
  • Both applications must share the same userbase (typically managed with an external directory using LDAP).

You shouldn't link to a non-Atlassian application using OAuth authentication, unless you trust the other application. Applications connected using application links have the ability to use OAuth to impersonate users and so are a potential security risk for the applications they connect to. If your server is compromised, the data there and on linked servers is at risk.

 

OAuth authentication redirects a user to log in to the remote application, after which tokens generated on their behalf are used to authorize requests made from the local applicationThe remote application handling the request uses the access permissions of the account with which the user logged in on that remote application.

Typical scenarios include:

  • You are setting up an application link between two applications that do not share the same set of users.
  • You want to continue using a link to an application that now allows public sign-on and the link was previously configured with a shared userbase. You can update your application link by changing OAuth (impersonation) to OAuth when editing the application link.

See Update an existing link on this page for instructions.

 

Atlassian OAuth with impersonation makes it easy for your users to benefit from the deep integrations between Atlasssian applications:

  • they're automatically authenticated on the other application and don't get asked to authorize requests.
  • they'll only see the information that they have permission to see. 

Impersonating authentication makes requests on behalf of the user who is currently logged in.

Note that Atlassian OAuth with impersonation can only be used for application links between Atlassian applications. Furthermore, it should only be used when the two applications share the same userbase, typically managed with an external directory using LDAP.

A typical scenario is:

  • You've set up an application link but your users still have to authenticate regularly. This can occur when the application link has been configured to not share the same userbase. If those applications do share the same userbase, you can update your application link by selecting OAuth (impersonation) when editing the application link.

See Update an existing link on this page for instructions.

 

You may need to update an existing application link to use OAuth authentication when:

  • you upgrade an Atlassian application to a version that uses version 5.2, or later, of application links. See the Application links version matrix.
  • the existing link uses Trusted Applications authentication, but your team can't see summary information from a developer tool such as Bitbucket Server in the Development panel in JIRA Software issues.
  • an existing application link uses OAuth, but your team can't see the details dialogs for the Development panel in JIRA Software issues.
  • you use a plugin that requires the OAuth authentication type.

Here's how to do that in JIRA Software, but the process is much the same for other Atlassian server products:

Go to the 'Configure Application Links' page in the admin area of the local application.

You may see a DEPRECATED lozenge beside links that need to be updated.

Click the pencil icon on the right to edit the configuration for the link you are updating.

In the 'Edit' dialog, set the local authentication for the link under 'Connections':

Choose either:

  • OAuth where both applications have different userbases.
  • OAuth (impersonation) if both applications share the same userbase, typically managed with an external directory using LDAP.

Make sure that that the authentication matches for the local and remote ends of both the incoming and outgoing directions.

Click Save changes.

Go to the 'Configure Application Links' page in the admin area of the remote application. Choose the instructions column here that matches the UI you see (they both achieve the same result):

Click the pencil icon on the right to edit the configuration for the link you are updating.

In the 'Edit' dialog, set the local authentication for the link under 'Connections':

Choose either:

  • OAuth where both applications have different userbases.
  • OAuth (impersonation) if both applications share the same userbase, typically managed with an external directory using LDAP.

Make sure that that the authentication matches for the local and remote ends of both the incoming and outgoing directions.

Click Save changes.

Click Edit for the application link you are updating.

In the 'Configure' dialog, click Outgoing Authentication and then the OAuth tab:

Now, select Enable 2-Legged OAuth, assuming that the applications have different userbases.

Optionally, select Enable 2-Legged OAuth with impersonation, if both applications share the same userbase, typically managed with an external directory using LDAP.

Click Update.

Now, click  Incoming Authentication  and then the OAuth tab:


Now, select Enable 2-Legged OAuth, assuming that the applications have different userbases.

Optionally, select Enable 2-Legged OAuth with impersonation, if both applications share the same userbase.

Click Update.

Note that:

  • Users who can see summarized data in the JIRA Software Development panel may not have permission to see all the information that contributed to those summaries and that is visible in the details dialogs (for example, for branches, commits and pull requests). That is, the details dialogs respect the access permissions that users have in the connected applications.

  • Your team members must have the 'View Development Tools' permission in JIRA Software to see the Development panel for an issue.

  • Application links between JIRA Software and Atlassian developer tools (Bitbucket Server, Bamboo, Crucible, FishEye) must have Trusted Applications and Basic Access authentication disabled.

  • If you run an application on port 443, you must use a valid SSL certificate (which is not self-signed) to get the full functionality available.

  • No labels

10 Comments

  1. Article says:

    When linking to JIRA applications, the remote API must be enabled in JIRA ( enable the 'Accept remote API calls' parameter in General Configuration).

    The word API appears nowhere on the referenced link:

    https://confluence.atlassian.com/adminjiraserver071/configuring-jira-application-options-802593101.html

     

    1. Thanks for calling that outBill Bailey.

      It turns out that the remote API has not been needed for application links for some time now, and further, that the setting to enable remote API access has been removed from JIRA as of 7.0.

      I've tidied up this page, and the others that refer to the remote API.

      1. You can still see "Remote API" when hitting two times "g" but you'll end up in the general configuration, where it's not listed anymore.

  2. After disabling the Trusted Application link and replacing it with OAuth according to these steps we get an error:

    Unfortunately, we've encountered problems connecting to JIRA: The server may be unreachable. Please ensure you are running JIRA 5.0 or higher.

    Is a restart of the linked applications needed?

    1. Hi,

      If you are using the new diagnostics UI you should get specific diagnostics messages to help you fix your application links problems. The error message you describe is not part of the new diagnostics feature, indicating that you are probably using an older version of our product. In general, if you have correctly set up OAuth you do not need to restart your application, which indicates that your application link is not working properly with OAuth. Would you be able to provide us with screenshots of how you have set up your application link with OAuth? Otherwise, please feel free to reach out to me directly to discuss further (sszasztoth@atlassian.com).

      Thanks,

      Szilard (Product Manager)

  3. Hi Szilard ,

    We are using License Information for JIRA i,e JIRA v6.4.7 and License Information for JIRA Plugins JIRA Agile v6.7.12 along with FishEye and Crucible 3.10.2 versions. And we disabled the Trusted Application link and replaced with OAuth according to the steps given above.

    I am facing the below 2 issues using the above OAuth settings::

    1) When we create a crucible review and linked with a specific JIRA Issue Key - it's taking time to update the Development panel as part of JIRA Issue Key tab.

    2) And I have added the "Review started" trigger in my JIRA Issue Type workflow to transition my JIRA issue from "Implementation In Progress" to "Code Review In Progress". when we create a crucible review by linking with specific JIRA Issue Key and start the crucible review, it should send the event to JIRA and JIRA issue state should transition automatically to "Code Review In Progress" from Implementation In Progress as per my workflow/trigger set. But it never happens, even though after getting the Development tab info with the linked review information as below against my JIRA Issue Key::

    Development

      • 1 review OPEN         Updated 36 minutes ago

     

    Review startedAutomatically transitions the issue when a related review is started in Crucible

    Please advice on how to troubleshoot shoot and fix these issues.

    Looks like these are due to my OAuth settings done. Thanks.

  4. Hi Szilard,

    The first 1) issue mentioned below, not seen and review information details are getting updated against Jira Issue Key within a minute.

    But Crucible events to trigger  Review started is not updating my Jira Issue Key workflow to transition automatically as needed.

     

    Review started

    Automatically transitions the issue when a related review is started in Crucible

    Thanks & Regards,

    Manju

    1. Hi Manju,

      Thanks for reaching out. I have replied to your Email directly.

      Best,

      Szilard

  5. AJ

    Using Confluence 6.0 Server.  When configure the application link for incoming authentication  this option is not there "Optionally, select Enable 2-Legged OAuth with impersonation, if both applications share the same userbase, typically managed with an external directory using LDAP."

    I am unable to set up the link OAuth with impersonation because Confluence does not have the option for impersonation.

     

    1. Hello. Did you find any solution for this?