Confluence Docs 3.0 : Setting Up Trusted Communication between JIRA and Confluence This page last changed on Sep 17, 2009 by smaddox. 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.
| 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.
- On this page: Prerequisites Why do we need Trusted Communication? Overview Configuring JIRA to Trust Confluence Configuring the Macro Plugin in Confluence Adding the Macro to a Confluence Page Viewing the Confluence Page Security Risks Troubleshooting Technical Overview of the Trusted Applications Authentication (TAA) Protocol ## 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, Go to the Confluence 'Administration Console'. To do this: Open the 'Browse' menu and select 'Confluence Admin'. The 'Administration Console' view will open. Select 'Plugins' in the left-hand panel. The 'Plugin Manager' screen appears, showing a list of installed plugins. Scroll down and click the 'JIRA Macros' link. The 'JIRA Macros' panel appears in the top middle of the screen, as shown below. Click 'Enable' or 'Disable' next to the following options: 'JIRA application trust support' – With this option enabled, Confluence will attempt trusted communication with JIRA whenever a user views a page containing the JIRA Issues or Portlet macro, provided criteria are met as described below. With this option disabled, Confluence will never attempt trusted communication with JIRA for these macros. Disable the above option if you do not intend to configure trusted communication between JIRA and Confluence. 'JIRA application trust warnings' – With this option enabled, Confluence will display all error and warning messages that may arise from a problem during trusted communication (assuming that trusted communication is enabled). With this option disabled, Confluence will suppress certain warnings. See troubleshooting below. Disable the above option if you have a large number of existing JIRA macros already on your Confluence instance, pointing at a diverse range of JIRA servers. Some of those JIRA servers may have a trusted communication link established (requiring the functionality to be enabled) while other JIRA servers may have no trusted communication link. In this case, you may want to turn off the warning messages so they do not appear on your Confluence pages where the JIRA macros point to non-trusting JIRA servers. 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. 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.
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: Configure JIRA to trust Confluence. Disable trusted communications for the JIRA macros in Confluence. Use the `anonymous` parameter in all your JIRA Issues and JIRA Portlet macros. | 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: Download the latest version of JIRA and then configure JIRA to trust Confluence. Disable trusted communications for the JIRA macros in Confluence. Use the `anonymous` parameter in all your JIRA Issues and JIRA Portlet macros. | Yes
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: 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). 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. JIRA stores all this information in the database. Making a trusted request from Confluence to JIRA: 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). 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. 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 Connect to LDAP, JIRA or Other Services Via SSL Single Sign-on Integration with JIRA and Confluence Troubleshooting the JIRA Issues Macro and Trusted Applications Attachments: JIRAMacrosPlugin.png (image/png)

Document generated by Confluence on Nov 05, 2009 23:26