This page last changed on Aug 21, 2011 by smaddox.
This page describes the Connect to JIRA step in the Confluence setup wizard.
Overview
You can connect your application to a JIRA server, to manage your users via JIRA and share information with JIRA. When you are installing the application, the setup wizard gives you the opportunity to configure the JIRA connection automatically. This is a quick way of setting up your JIRA integration with the most common options.
You can also configure the JIRA connections via the application administration screens. In that case, you will need to set up connections individually. There are two parts to the integration process:
- A peer-to-peer link between JIRA and the application for sharing information and facilitating integration features. This link is set up via Application Links.
- A client-server link between the application and JIRA for delegating user and group management to your JIRA server.
Requirements: You need JIRA 4.3 or later.
|
|
Connecting to JIRA in the Setup Wizard

Screenshot above: Connecting to JIRA in the Confluence setup wizard
Enter the following information:
- JIRA Base URL – The web address of your JIRA server. Examples:
- JIRA Administrator Login: Username – Enter the username of a user with the 'JIRA System Administrators' global permission in JIRA.
- JIRA Administrator Login: Password – Enter the password that the above user uses to sign in to JIRA.
- Confluence Base URL – JIRA will use this URL to access your Confluence server. The URL you give here will override the base URL specified in your Confluence administration console, for the purposes of the JIRA connection.
- User Groups – Specify one or more JIRA groups whose members should be able to use Confluence. The default group is
jira-users . (These groups will receive the 'can use' permission in Confluence.)
- Admin Groups – Specify one or more JIRA groups whose members should have administrative access to Confluence. The default group is
jira-administrators . (These groups will receive the 'Confluence system administrator' and 'Confluence administrator' permissions in Confluence.)
Troubleshooting
This section describes the possible problems that may occur when integrating your application with JIRA via the setup wizard, and the solutions for each problem.
Symptom |
Cause |
Solution |
The setup wizard displays one of the following error messages:
- Failed to create application link from JIRA server at <URL> to this <application> server at <URL>.
- Failed to create application link from this <application> server at <URL> to JIRA server at <URL>.
- Failed to authenticate application link from JIRA server at <URL> to this <application> server at <URL>.
- Failed to authenticate application link from <application> server at <URL> to this JIRA server at <URL>.
|
The setup wizard failed to complete registration of the peer-to-peer application link with JIRA. JIRA integration is only partially configured. |
Remove the partial configuration if it exists, try the 'Connect to JIRA' step again, and then continue with the setup. Detailed instructions are below. |
The setup wizard displays one of the following error messages:
- Failed to register <application> configuration in JIRA for shared user management. Received invalid response from JIRA: <response>
- Failed to register <application> configuration in JIRA for shared user management. Received: <response>
|
The setup wizard failed to complete registration of the client-server link with JIRA for user management. The peer-to-peer link was successfully created, but integration is only partially configured. |
Remove the partial configuration if it exists, try the 'Connect to JIRA' step again, and then continue with the setup. Detailed instructions are below. |
The setup wizard displays the following error message:
- Error setting Crowd authentication
|
The setup wizard successfully established the peer-to-peer link with JIRA, but could not persist the client-server link for user management in your config.xml file. This may be caused by a problem in your environment, such as a full disk. |
Please investigate and fix the problem that prevented the application from saving the configuration file to disk. Then remove the partial configuration if it exists, try the 'Connect to JIRA' step again, and then continue with the setup. Detailed instructions are below. |
The setup wizard displays the following error message:
- Error reloading Crowd authentication
|
The setup wizard has completed the integration of your application with JIRA, but is unable to start synchronizing the JIRA users with your application. |
Restart your application. You should then be able to continue with the setup wizard. If this solution does not work, please contact Atlassian Support. |
The setup wizard displays the following error message:
- An error occurred: java.lang.IllegalStateException: Could not create the application in JIRA/Crowd (code: 500). Please refer to the logs for details.
|
The setup wizard has not completed the integration of your application with JIRA. The links are only partially configured. The problem occurred because there is already a user management configuration in JIRA for this <application> URL. |
Remove the partial configuration if it exists, try the 'Connect to JIRA' step again, and then continue with the setup. Detailed instructions are below. |
No users can log in after you have set up the application with JIRA integration. |
Possible causes:
- There are no users in the group that you specified on the 'Connect to JIRA' screen.
- For FishEye: There are no groups specified in the 'groups to synchronize' section of your administration console.
|
Go to JIRA and add some usernames to the group.
For FishEye: Go to the FishEye administration screens and specify at least one group to synchronize. The default is 'jira-users'.
If this solution does not work, please contact Atlassian Support. |
Solution 1: Removing a Partial Configuration – The Easiest Way
If the application's setup wizard fails part-way through setting up the JIRA integration, you may need to remove the partial configuration from JIRA before continuing with your application setup. Please follow the steps below.
Remove the partial configuration if it exists, try the 'Connect to JIRA' step again, and then continue with the setup wizard:
- Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
- Click the 'Administration' link on the JIRA top navigation bar.
- Remove the application link from JIRA, if it exists:
- Click 'Application Links' in the JIRA administration menu. The 'Configure Application Links' page will appear, showing the application links that have been set up.
- Look for a link to your application. It will have a base URL of the application linked to JIRA. For example:
- If you want to remove a link between JIRA and FishEye, look for the one where the 'Application URL' matches the base URL of your FishEye server.
- If you want to remove a link between JIRA and Confluence, look for the one where the 'Application URL' matches the base URL of your Confluence server.
- Click the 'Delete' link next to the application link that you want to delete.
- A confirmation screen will appear. Click the 'Confirm' button to delete the application link.
- Remove the user management configuration from JIRA, if it exists:
Unable to render {include} The included page could not be found.
- Go back to the setup wizard and try the 'Connect to JIRA' step again.
Solution 2: Removing a Partial Configuration – The Longer Way
If solution 1 above does not work, you may need to remove the partial configruration and then add the full integration manually. Please follow these steps:
- Skip the 'Connect to JIRA' step and continue with the setup wizard, to complete the initial configuration of the application.
- Log in to JIRA as a user with the 'JIRA System Administrators' global permission.
- Click the 'Administration' link on the JIRA top navigation bar.
- Remove the application link from JIRA, if it exists:
- Click 'Application Links' in the JIRA administration menu. The 'Configure Application Links' page will appear, showing the application links that have been set up.
- Look for a link to your application. It will have a base URL of the application linked to JIRA. For example:
- If you want to remove a link between JIRA and FishEye, look for the one where the 'Application URL' matches the base URL of your FishEye server.
- If you want to remove a link between JIRA and Confluence, look for the one where the 'Application URL' matches the base URL of your Confluence server.
- Click the 'Delete' link next to the application link that you want to delete.
- A confirmation screen will appear. Click the 'Confirm' button to delete the application link.
- Remove the user management configuration from JIRA, if it exists:
Unable to render {include} The included page could not be found.
- Add the application link in JIRA again, so that you now have a two-way trusted link between JIRA and your application:
- Click 'Add Application Link'. Step 1 of the link wizard will appear.
- Enter the server URL of the application that you want to link to (the 'remote application').
- Click the 'Next' button.
- Enter the following information:
- 'Create a link back to this server' – Tick this check box to add a two-way link between the two applications.
- 'Username' and 'Password' – Enter the credentials for a username that has administrator access to the remote application.
Note: These credentials are only used to authenticate you to the remote application, so that Application Links can make the changes required for the new link. The credentials are not saved.
- 'Reciprocal Link URL' – The URL you give here will override the base URL specified in your remote application's administration console, for the purposes of the application links connection. Application Links will use this URL to access the remote application.
- Click the 'Next' button.
- Enter the information required to configure authentication for your application link:
- 'The servers have the same set of users' – Tick this check box, because the users are the same in both applications.
- 'These servers fully trust each other' – Tick this check box, because you trust the code in both applications and are sure both applications will maintain the security of their private keys.
For more information about configuring authentication, see Configuring Authentication for an Application Link.
- Click the 'Create' button to create the application link.
- Configure a new connection for user management in JIRA:
- Go to the JIRA administration screen for configuring the applications that have been set up to use JIRA for user management:
- In JIRA 4.3: Click 'Other Applications' in the 'Users, Groups & Roles' section of the JIRA administration screen.
- In JIRA 4.4: Select 'Administration' > 'Users' > 'JIRA User Server'.
- Add an application.
- Enter the application name and password that your application will use when accessing JIRA.
- Enter the IP address or addresses of your application. Valid values are:
- A full IP address, e.g.
192.168.10.12 .
- A wildcard IP range, using CIDR notation, e.g.
192.168.10.1/16 . For more information, see the introduction to CIDR notation on Wikipedia and RFC 4632.
- Save the new application.
- Set up the JIRA user directory in the application.
- For Confluence:
- Go to the Confluence Administration Console.
- Click 'User Directories' in the left-hand panel.
- Add a directory and select type 'Atlassian JIRA'.
- Enter the following information:
- Name – Enter the name of your JIRA server.
- Server URL – Enter web address of your JIRA server. Examples:
- Application name and Application password – Enter the values that you defined for Confluence in the settings on JIRA.
- Save the directory settings.
- Define the directory order by clicking the blue up- and down-arrows next to each directory on the 'User Directories' screen.
For details see Connecting to Crowd or JIRA for User Management.
- For FishEye/Crucible:
- Click 'Authentication' on the FishEye/Crucible 'Admin Menu'.
- Click 'Edit' in the section titled 'JIRA or Crowd Authentication'.
- Enter the following information:
- Application name and Application password – Enter the values that you defined for your application in the settings on JIRA.
- JIRA/Crowd URL – The web address of your JIRA server. Examples:
- Auto-add – Select 'Create a FishEye/Crucible user on successful login' (default) to ensure that your JIRA users will be automatically enrolled into FishEye/Crucible when they first log in via JIRA.
- Synchronize users with JIRA/Crowd – Select 'Yes' (default) to ensure that JIRA will synchronize all changes in the user information on a regular basis. The synchronization interval is set to 60 minutes (1 hour) by default.
- Single sign on (SSO) – This option is not available when using JIRA for user management.
- Groups of users to synchronize – Select at least one group to synchronize. The default is 'jira-users'.
- Click 'Apply changes'.
Notes
- When you connect to JIRA in the setup wizard, the setup procedure will configure Trusted Applications authentication for your application. Please be aware of the following security implications:
- Trusted applications are a potential security risk. When you configure Trusted Applications authentication, you are allowing one application to access another as any user. This allows all of the built-in security measures to be bypassed. Do not configure a trusted application unless you know that all code in the application you are trusting will behave itself at all times, and you are sure that the application will maintain the security of its private key.
- In the next step, you will specify the username and password of your Confluence system administrator. If you have connected to JIRA, the setup wizard will add the Confluence administrator's username and password to both JIRA and Confluence. This is done so that you can still access Confluence even if JIRA is down. Please note that the password in Confluence is not linked to the password in JIRA. If you subsequently change the administrator's password, only the password in JIRA will change. This is because the JIRA user directory is placed first in the list of user directories. See Managing Multiple Directories.
User Management Limitations and Recommendations
Confluence Setup Guide
Configuring Application Links
|