Setting Up Trusted Communication between JIRA and Confluence

An administrator can configure JIRA and Confluence to communicate in a trusted way, so that Confluence can request information from JIRA on behalf of the currently logged-in user. JIRA will not ask the user to log in again or to supply a password.

When JIRA is configured to trust Confluence in this way, we call Confluence the 'trusted application' and JIRA the 'trusting application'.

Trusted communication is used when embedding information from one application (e.g. a list of JIRA issues) into another application (e.g. a Confluence page). Currently only JIRA can be configured to trust Confluence, and only the following two macros have been enhanced to use trusted communication:

• JIRA Issues macro
• JIRA Portlet macro

Further implementations will follow, especially as we roll out the tight integration required between Atlassian products for JIRA Studio.

On this page:

Prerequisites

• JIRA 3.12.0 or later.
• Confluence 2.7.0 or later.
• In order to authenticate successfully against JIRA, the Confluence user must also be registered as a JIRA user with the same username.

  Common user base recommended

  It is highly recommended that your JIRA and Confluence instances share a common user base, rather than two separate user bases with duplicated usernames. You will receive an error if Confluence passes JIRA a username which JIRA cannot recognise. Also, with separate user bases you run the risk that the same username may be used by two different people. The trusted application does not supply the user's password, so the trusting application will assume the username belongs to the user registered in the trusting application's own user base.

  Tip: Try Atlassian Crowd for a tidy user management solution.

Why do we need Trusted Communication?

The JIRA Issues and the JIRA Portlet macros allow you to embed a list of JIRA issues into a Confluence page. Prior to Confluence 2.7, if you wanted to display JIRA issues that had restricted viewing, then you needed to store the JIRA user's credentials (username and password) in the macro code directly on the Confluence page. This was not very secure.

The reasons we require the user credentials are:

• Your JIRA instance might not be public, and you might not want to allow anonymous access to your issues.
• You might have security restrictions on some of your issues. So you don't want to allow someone to leak data from your JIRA project by using the JIRA Issues Macro on a Confluence page.

Overview

Here is a summary of the integration points in a trusted communications relationship. Each of the following points is described in more detail in the sections below.

• A JIRA System Administrator configures JIRA to trust Confluence.
• A Confluence System Administrator configures the macro plugin to use (or not use) trusted communication.
• A Confluence user adds one of the macros to a Confluence page.
• A Confluence user or anonymous user views the Confluence page.

Configuring JIRA to Trust Confluence

Trust only has to be established once between the two applications. Once trust has been established, it is entirely transparent to the Confluence users.

Using the JIRA Administration Console, the JIRA System Administrator defines Confluence as a trusted application by specifying the Confluence instance's URL and other information. Refer to the JIRA documentation for details.

Configuring the Macro Plugin in Confluence

By default, Confluence ships with trusted communication enabled for the following macros:

• JIRA Issues macro
• JIRA Portlet macro

A Confluence System Administrator can decide on the level of trusted communication used by the macros. The different levels are:

• Ignore trusted communications altogether. Trusted communication is turned off at the global level.
• Perform trusted communications whenever the macro is used on a Confluence page, but do not show certain warning messages.
• Perform trusted communications whenever the macro is used on a Confluence page, and show all warning messages. This is the default configuration.

To change the default trusted communication level for the JIRA Macros plugin,

Screenshot: JIRA Macros panel in Plugin Manager

Adding the Macro to a Confluence Page

The Confluence user can add and edit the macros as described on the following pages:

• Using the JIRA Issues macro
• Using the JIRA Portlet macro

  Remove the username and password from your macro markup code

  Prior to Confluence 2.7, you needed to include a username and password in the macro markup code if you wanted to display JIRA issues which had restricted viewing. Once your administrator has set up trusted communication between Confluence and JIRA, you no longer need to include a username and password in the markup code for your JIRA macros.

  The following options are available for determining the issues which will be retrieved from JIRA and displayed on the Confluence page:

  What you want to do	Macro parameter	URL parameter	Comments
  Display the JIRA issues which the logged-in user is authorised to see. And if the user is not logged in, display only issues which allow unrestricted viewing.			Do not specify any authentication parameters. In this case, the behaviour depends on the way your administrator has set up trusted communication between JIRA and Confluence. Here is a summary of the behaviour. If trusted communication is enabled, the authorisation will work seamlessly. When a logged-in user views your page, they will see only the JIRA issues they are allowed to see. And if they are not logged in, they will see only the issues which allow unrestricted viewing. If trusted communication is disabled, the Confluence page will show only the JIRA issues which allow unrestricted viewing.
  Ensure that Confluence will display only the JIRA issues which allow unrestricted viewing.	anonymous		Regardless of who the user is (logged in or not), the Confluence page will show only anonymously-visible issues. Confluence will not attempt to set up a trusted communication link with JIRA in this case.
  Use a pre-determined username and password to access the JIRA issues.		&os_username=MYNAME&os_password=MYPASSWORD	Not recommended. Prior to Confluence 2.7, this was the only way of displaying issues with restricted viewing. For Confluence 2.7 and later, this method will still work. Confluence will not attempt to set up a trusted communication link with JIRA in this case.

  
  Refer to the section below for details of what happens when a user views a Confluence page containing a JIRA macro.

Viewing the Confluence Page

When a user views a Confluence page which contains a JIRA Issues or JIRA Portlet macro, this is what happens:

• If the macro markup contains an explicit username and password in the URL parameter, Confluence will not request trusted communication with JIRA. Confluence will retrieve the JIRA issues which the specified username is authorised to see. This behaviour is the same as Confluence versions prior to 2.7.
• If the macro markup contains the anonymous parameter, Confluence will retrieve only the JIRA issues which allow unrestricted viewing. Confluence will not attempt to set up a trusted communication link with JIRA in this case.
• If the user is anonymous (not logged in), Confluence will retrieve only the JIRA issues which allow unrestricted viewing. Confluence will not attempt to set up a trusted communication link with JIRA in this case.
• If trusted communication is disabled via the Plugin Manager in Confluence, then Confluence will not request trusted communication with JIRA. So if there is no explicit username and password in the markup code, Confluence will retrieve only the JIRA issues which allow unrestricted viewing. This behaviour is the same as Confluence versions prior to 2.7.
• If trusted communication is enabled via the Plugin Manager in Confluence:
  • If the user is logged in, then Confluence attempts trusted communication with JIRA. Confluence sends the username to JIRA. JIRA returns a set of issues which that username is authorised to access, based on the JIRA user base and the JIRA groups and permissions. Confluence displays those issues on the page.
  • If JIRA or Confluence encounters a problem during the trusted communication process, an error message may appear on the Confluence page above the macro output – see troubleshooting below.

Security Risks

Please take the following considerations into account when setting up trusted communication:

• When you configure JIRA to trust an application, you are allowing the application to access JIRA in the name of a particular user. The trusted application passes JIRA the user's login name, but no other authentication information. JIRA does not request the user's password. By doing this, you are bypassing JIRA's authentication mechanism.
• Do not configure a trusted application unless you trust all code in that application to behave itself at all times.
• Trusted communication uses public/private key cryptography to establish the identity of the trusted server. The trusted application needs to maintain the security of its private key. Confluence stores its private key in the database. So you must be sure that the Confluence database is secure, and also any full backups of the database.
• Ensure that you specify an IP address for your Confluence site when configuring trusted applications in JIRA. Do not use the wild card *.*.*.* as the IP address. Failure to configure IP address restrictions is a security vulnerability, allowing an unknown site to log into your JIRA site under a user's login ID.
• Be aware of the risks associated with using separate user bases, as explained above. We strongly recommend a common user base between the trusted and trusting applications.
• When configuring an application to trust another application, you should use a trusted network or SSL to protect the sensitive information passed between the applications during the configuration procedure. This will help to prevent man-in-the-middle attacks.

Troubleshooting

Below are the warning messages which may appear on your Confluence page, above the output of the JIRA Issues or JIRA Portlet macro.

Consult Troubleshooting the JIRA Issues Macro and Trusted Applications for further troubleshooting.

Technical Overview of the Trusted Applications Authentication (TAA) Protocol

Read this section if you want a bit more information on the technical side of things.

Atlassian has developed its own protocol to set up trust between JIRA and Confluence. Below is a technical overview of the process.

Configuring JIRA to trust Confluence:

1. When the JIRA System Administrator provides the base URL of the Confluence instance, JIRA requests a trusted application authentication certificate from Confluence. The certificate contains Confluence's trusted application ID and public key (generated specifically for use with the TAA protocol).
2. JIRA validates the certificate and asks the System Administrator for a few extra details about the trust relationship, such as a name for the Confluence instance, timeout, allowed IP addresses and allowed request URLs.
3. JIRA stores all this information in the database.

Making a trusted request from Confluence to JIRA:

1. Confluence sends a web request to JIRA, appending additional headers to the request, including:
   • Timestamp (nonce) of the request + user name of the currently logged-in Confluence user, encrypted with a symmetric key (generated on the fly).
   • The symmetric key, encrypted with Confluence's private key.
   • Confluence's application ID (as displayed when trusted communication was established).
2. JIRA attempts to decode the encrypted headers, using the stored information about the relationship. It conducts the following checks to validate the request:
   • The trusted application ID refers to a valid trusted application.
   • The given username exists in the JIRA user base.
   • The agreed timeout has not expired.
   • The request originated from a trusted IP address.
   • The resource being requested matches those specified in the URL match list.
3. If any of these checks fails, a response is sent to Confluence indicating the reason for failure. Otherwise, JIRA will authenticate the specified user for the duration of the single request, and respond with the resources (i.e. the JIRA issues).

RELATED TOPICS

JIRA Issues Macro
JIRA Portlet Macro
Connecting to LDAP or JIRA or Other Services via SSL
Single Sign-on Integration with JIRA and Confluence
Troubleshooting the JIRA Issues Macro and Trusted Applications