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 authentication protocol.

Atlassian recommends OAuth authentication for application links because of the greater security provided by that protocol. We no longer recommend the Trusted Applications and Basic Access authentication types. 

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

 

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

 

OAuth authentication

OAuth with impersonation

Description
  • Uses a pre-configured user, and not the logged-in user, when making a request. 
  • The server handling the request determines the level of access to use based on the access permissions of that pre-configured user, and this is used for requests from all users. 
  • Makes requests on behalf of the user who is currently logged in. 
  • Users see only the information that they have permission to see. 
Benefits
  • Can be used where the applications have different user bases.
  • Users don't need to authenticate whenever they request restricted resources from the remote application.
Requirements
  • 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. Linked applications 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 always uses a pre-configured user, and not the logged-in user, when making a request. The server handling the request determines the level of access to use based on the access permissions of that pre-configured user, and this is used for requests from all users. 

A typical scenario is setting up an application link between two applications that trust each other and that do not share the same set of users.

Newly created application links use OAuth by default and automatically enable both 3-legged OAuth and 2-legged OAuth.

Note that application links between Jira Software and Atlassian developer tools (Bitbucket Server, Bamboo, Crucible, Fisheye) must have Trusted Applications and Basic Access authentication disabled.

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

  • 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. You need to update the link to use OAuth.
  • an existing application link uses OAuth, but your team can't see the details dialogs for the Development panel in Jira Software issues. You need to enable 2-legged OAuth for the link.
  • you use a plugin that requires the OAuth authentication type.

When you update an older application link to use OAuth authentication, 3-legged authentication is applied by default, but you need to explicitly enable 2-legged OAuth.

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

  1. Go to the admin area in Jira Software and click Add-ons > Application Links
  2. Click Edit (in the Actions menu) for the application link you want to update.
  3. Click Outgoing Authentication and then:
    1. Disable both Trusted Applications and Basic Access authentication, if necessary.
    2. Click the OAuth tab and check Enable outgoing 2-Legged OAuth requests.
    3. Click Update.

       
       
  4. Click  Incoming Authentication and then:
    1. Disable both Trusted Applications and Basic Access authentication, if necessary.
    2. Click the OAuth tab and check Allow 2-Legged OAuth.
    3. Click Update.

       

 

The application link update process will log you into the linked application (such as Bamboo) for a short time to configure that end of the link, before returning you to Jira Software.

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.

  • 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.

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

Impersonating authentication makes requests on behalf of the user who is currently logged in. People will see only the information that they have permission to see. 

Typical scenarios include:

  • you've set up an application link but users still have to authenticate regularly. This can occur when the application link has been configured to not share the same user base. If those applications do share the same userbase, you can update your application link by selecting  Allow user impersonation through 2-Legged OAuth when editing the application link.
  • 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 user base. You can update your application link authentication by clearing  Allow user impersonation through 2-Legged OAuth when editing the application link.

Here's how to do that in Jira Software (the process is much the same for other Atlassian server products):

  1. Go to the admin area in Jira Software and click Add-ons > Application Links
  2. Click Edit (in the Actions menu) for the application link you want to update.
  3. Click Incoming Authentication.
  4. Click the OAuth tab and either (or clear) Allow user impersonation through 2-Legged OAuth.
  5. Click Update.

     

 

You can reset the OAuth authentication for an existing application link by disabling OAuth and then re-enabling it. You might need to do this when the OAuth consumer key has gone stale (you're seeing the  consumer_key_unknown error).

 

  • No labels