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.

Trusted communication is used when embedding information from one application (for example, a list of JIRA issues) into another application (for example, a Confluence page).

Potential security risk

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, so you must also be sure that the trusted application will maintain the security of its private key. Read the details of the security risks below.

Prerequisites

The following setup is required:

  • JIRA 4.2.0 or later.
  • Confluence 3.5.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.

Note: 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 macro allows 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. You many not 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.

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.

You can use Application Links to enable trust relationships between two applications. Linking two applications allows you to share information and access one application's functions from within the other.

You can configure an application link to use Trusted Applications as the authentication mechanism. For instructions, see Linking to Another Application.

Adding the macro to a Confluence page

The Confluence user can add and edit the macros as described on the following page: JIRA Issues macro.

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.

Viewing the Confluence page

When a user views a Confluence page which contains a JIRA Issues 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 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 macro.

Warning Message

Cause

Solution

Warning Message Can be Turned Off?

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

JIRA is running over SSL

Add JIRA's SSL Certificate to the Java Keystore

No

The JIRA server does not recognise your user name. Issues have been retrieved anonymously.

The logged-in Confluence user is not registered in the JIRA user base.

Add the username to your JIRA user base. It is highly recommended that your JIRA and Confluence instances share a common user base.

No

The JIRA server does not trust this Confluence instance for user authentication. Issues have been retrieved anonymously. You can set the macro to always use an anonymous request by setting the 'anonymous' parameter to 'true'.

Your JIRA instance has not been configured to trust your Confluence instance.

One of the following solutions:

Yes

The JIRA server does not support trust requests. Issues have been retrieved anonymously. You can set the macro to always use an anonymous request by setting the 'anonymous' parameter to 'true'.

Your JIRA instance is not able to handle trusted communications (i.e. the JIRA version is earlier than 3.12.0).

One of the following solutions:

Yes

Failed to login trusted application: confluence:14159892 due to: com.atlassian.security.auth.trustedapps.CertificateTooOldException: OLD_CERT; Certificate too old.

There is a date/time difference between the JIRA server and Confluence server.

-

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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport