Integrating Crowd with Atlassian JIRA

Atlassian's popular JIRA issue management system takes advantage of the OSUser framework and can quickly be configured to use OSUser to link in single or multiple directory servers through Crowd. Crowd provides integration libraries for the OpenSymphony OSUser module, which has a simple-to-use API for user management that allows pluggable implementations. You can read more about the OSUser API at http://www.opensymphony.com/osuser/.

Currently Crowd supports centralised authentication and single sign-on for JIRA versions 3.7.4 and later.

JIRA 4.2 and newer versions

Because of changes in our authentication framework, JIRA 4.2 and newer versions will work only with Crowd 2.0.7 and newer versions. If you are using an older version of Crowd, please upgrade it before integrating with JIRA.

Please check that this documentation applies to your version of Crowd

Please check the Crowd release number in this documentation against your version of Crowd. If you are using a different version of Crowd, you can find the appropriate documentation under 'Previous Versions' on the Crowd documentation homepage.

On this page:

Prerequisites

Do not deploy multiple Atlassian applications in a single Tomcat container

Deploying multiple Atlassian applications in a single Tomcat container is not supported. We do not test this configuration and upgrading any of the applications (even for point releases) is likely to break it. There are also a number of known issues with this configuration. See this FAQ for more information.

In addition, there are practical reasons for recommending that you do not deploy multiple Atlassian applications in a single Tomcat container. Firstly, you will need to shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in the Tomcat container will be inaccessible.

Download and install Crowd. Refer to the Crowd installation guide for instructions. We will refer to the Crowd root folder as CROWD.
Download and install JIRA (version 3.7.4 or later). Refer to the JIRA installation guide for instructions. We will refer to the JIRA root folder as JIRA. For the purposes of this document, we will assume that you have used the 'Standalone' (i.e. the easier and recommended) installation method of JIRA. If you need to install JIRA as an EAR/WAR, simply explode the EAR/WAR and make the necessary changes as described below, then repackage the EAR/WAR.
Run the JIRA Setup Wizard, as described in the JIRA documentation. During this setup process, you will define the JIRA administrator's username and password. It is easier to do this before you integrate JIRA with Crowd.
After setting up JIRA, shut down JIRA before you begin the integration process described below.

Step 1. Configuring Crowd to talk to JIRA

1.1 Prepare Crowd's Directories/Groups/Users for JIRA

The JIRA application will need to locate users from a directory configured in Crowd. You will need to set up a directory in Crowd for JIRA. This directory may be any Crowd-configured directory, such as an LDAP directory hooked up to Crowd or a Crowd internal directory. For information on how to do this, see Adding a Directory.

We will assume that the directory is called JIRA Directory in Crowd for the rest of this document. It is possible to assign more than one directory for an application, but for the purposes of this example, we will use JIRA Directory in Crowd to house JIRA users.
JIRA also requires particular groups to exist in the directory in order to authenticate users. You need to ensure that these three groups exist in the JIRA Directory in Crowd:
- jira-users
- jira-developers
- jira-administrators
You also need to ensure that the JIRA Directory in Crowd contains at least one user who is a member of all three groups. You can either:
- If you have an existing JIRA deployment and would like to import existing groups and users into Crowd, use the JIRA Importer tool by navigating to Users > Import Users > Atlassian Importer. Select 'JIRA' as the Atlassian Product and the JIRA Directory in Crowd as the directory into which JIRA users will be imported. For details please see Importing Users from Atlassian JIRA. If you are going to import users into Crowd, you need to do this now before you proceed any further.
  OR:
- If you don't wish to import your JIRA users, use the Crowd Administration Console to create the three groups, then create at least one user in the JIRA Directory in Crowd and add them to the three JIRA-specific groups (above). The Crowd documentation has more information on creating groups, creating users and assigning users to groups.

Error will occur in JIRA if the required groups do not exist

JIRA expects that the group names mentioned above will exist. If you need to use different group names, you may want to remove the above pre-existing groups from JIRA's Global Permissions. If the above groups do not exist somewhere in Crowd, you will receive an error when you try to remove the groups from JIRA's Global Permissions.

1.2 Define the JIRA Application in Crowd

If multiple versions of JIRA are being connected to Crowd, ensure you define an application in Crowd for each one

Crowd needs to be aware that the JIRA application will be making authentication requests to Crowd. We need to add the JIRA application to Crowd and map it to the JIRA Directory in Crowd.

Log in to the Crowd Administration Console and navigate to Applications > Add Application.
Complete the 'Add Application' wizard for the JIRA application. See the instructions. The Name and Password values you specify in the 'Add Application' wizard must match the application.name and application.password that you will set in the JIRA/atlassian-jira/WEB-INF/classes/crowd.properties file. (See Step 2 below.)

Unknown macro: {HTMLcomment} http://tinyurl.com/crowd-jirausers

1.3 Specify which users can log in to JIRA

Once Crowd is aware of the JIRA application, Crowd needs to know which users can authenticate (log in) to JIRA via Crowd. As part of the 'Add Application' wizard, you will set up your directories and group authorisations for the application. If necessary, you can adjust these settings after completing the wizard. Below are some examples.

You can either allow entire directories to authenticate, or just particular groups within the directories. In our example, we will allow the jira-users, jira-developers and jira-administrators groups within the JIRA Directory in Crowd to authenticate:

With this example, only users who are members of the jira-users, jira-developers and jira-administrators groups will be able to authenticate against JIRA.

For details please see Specifying which Groups can access an Application.

1.4 Specify the address from which JIRA can log in to Crowd

As part of the 'Add Application' wizard, you will set up JIRA's IP address. This is the address which JIRA will use to authenticate to Crowd. If necessary you can add a hostname, in addition to the IP address, after completing the wizard. See Specifying an Application's Address or Hostname.

Step 2. Configuring JIRA to talk to Crowd

2.1 Install the Crowd Client Libraries into JIRA

JIRA needs Crowd's client libraries in order to be able to delegate user authentication to the Crowd application. As stated earlier, we are going to be modifying the JIRA application by editing the standalone application, which is an exploded WAR stored in JIRA/atlassian-jira.

If you are using the Crowd WAR distribution, then you will need to get the CROWD client libraries from the standalone distribution, available on our download site.
Copy the Crowd client libraries and configuration files to JIRA:

Copy From

Copy To

CROWD/client/crowd-integration-client-X.X.X.jar

JIRA/atlassian-jira/WEB-INF/lib

CROWD/client/conf/crowd.properties

JIRA/atlassian-jira/WEB-INF/classes

Duplicate Crowd Client libraries in your classpath

The crowd-integration-client always needs to be of the same version as the Crowd server. Therefore you need to delete the existing crowd-integration-clien-X.X.X.jar file from JIRA's WEB-INF/lib directory and replace it with CROWD/client/crowd-integration-client-X.X.X.jar instead of just copying it over. Also, renaming the existing crowd-integration-client jar will not work as JIRA will start with duplicate Crowd Client libraries in its classpath.
If you are using JIRA 3.11 or earlier, you will need to remove the seraph-0.7.12.jar file from JIRA's WEB-INF/lib/ directory and replace it with the following file:
http://repository.atlassian.com/maven2/com/atlassian/seraph/atlassian-seraph/0.10/atlassian-seraph-0.10.jar
If you are using JIRA 3.12.2 or earlier, you will need to update JIRA's xfire libraries:
- Remove the xfire-all-1.2.1.jar file from JIRA's WEB-INF/lib/ directory.
- Copy the following two files from Crowd's client/lib/ directory to JIRA's WEB-INF/lib/ directory:
  - xfire-aegis-1.2.6.jar
  - xfire-core-1.2.6.jar
Replace JIRA's cache configuration file:

Copy From

Replace File

CROWD/client/conf/crowd-ehcache.xml

JIRA/atlassian-jira/WEB-INF/classes/crowd-ehcache.xml

Edit JIRA/atlassian-jira/WEB-INF/classes/crowd.properties. Change the following properties:

Key	Value
application.name	`jira` The application name must match the name that you specified when you defined the application in Crowd (see Step 1 above).
application.password	The password must match the one that you specified when you defined the application in Crowd (see Step 1 above).
crowd.server.url	http://localhost:8095/crowd/services/ If your Crowd server's port is configured differently from the default (i.e. 8095), set it accordingly.
session.validationinterval	Set to 0, if you want authentication checks to occur on each request. Otherwise set to the number of minutes between request to validate if the user is logged in or out of the Crowd SSO server. Setting this value to 1 or higher will increase the performance of Crowd's integration.

You can read more about optional settings in the crowd.properties file.

2.2 Configure JIRA to use Crowd's Authenticator

Now that the Crowd client libraries exist, we need to configure JIRA to use them.

Note: if you are migrating/upgrading a JIRA instance that already uses Crowd, you will need to merge these files (not overwrite them).

Edit the JIRA config file JIRA/atlassian-jira/WEB-INF/classes/osuser.xml. Comment out any existing authentication providers and uncomment/insert the Crowd providers:

<!-- This is where JIRA's credentials checking can be configured.  For instance, see
http://www.atlassian.com/software/jira/docs/latest/ldap.html -->
<opensymphony-user>
  <authenticator class="com.opensymphony.user.authenticator.SmartAuthenticator" />

<!-- You will need to uncomment the Crowd providers below to enable Crowd integration -->
  <provider class="com.atlassian.crowd.integration.osuser.CrowdCredentialsProvider"/>
  <provider class="com.atlassian.crowd.integration.osuser.CrowdAccessProvider"/>
  <provider class="com.atlassian.crowd.integration.osuser.DelegatingProfileProvider">
    <property name="provider-1">com.atlassian.crowd.integration.osuser.CrowdProfileProvider</property>
    <property name="provider-2">com.atlassian.jira.user.ExternalEntityJiraProfileProvider</property>
    <property name="provider-2-exclusive-access">true</property>
  </provider>

<!-- CROWD:START  - The providers below here will need to be commented out for Crowd integration -->
<!--
  <provider class="com.atlassian.core.ofbiz.osuser.CoreOFBizCredentialsProvider">
    <property name="exclusive-access">true</property>
  </provider>

  <provider class="com.opensymphony.user.provider.ofbiz.OFBizProfileProvider">
    <property name="exclusive-access">true</property>
  </provider>

  <provider class="com.opensymphony.user.provider.ofbiz.OFBizAccessProvider">
    <property name="exclusive-access">true</property>
  </provider>
-->
<!-- CROWD:END -->

</opensymphony-user>

View JIRA/atlassian-jira/WEB-INF/classes/propertyset.xml. If there is no entry for the CrowdPropertySet, add the following <propertyset> item at the end of the file as the last <propertyset> item:
```
<propertyset name="crowd" class="com.atlassian.crowd.integration.osuser.CrowdPropertySet"/>
```
At this stage, JIRA is set up for centralised authentication. If you wish, you can now enable single sign-on (SSO) to JIRA. This will ensure that JIRA's authentication and access request calls will be performed using Seraph. When authentication or access request calls are performed versus the OSUser framework, the JIRA stack will call the Crowd providers and propertyset implementations.

Edit the JIRA/atlassian-jira/WEB-INF/classes/seraph-config.xml file. Comment out the authenticator node:
```

```
Add a new authenticator, choosing the one relevant to your version of JIRA:
- If you are using JIRA 4.2 or later:
```
<authenticator class="com.atlassian.crowd.integration.seraph.v22.JIRAAuthenticator"/>
```
- If you are using JIRA 4.1.2 or earlier:
```
<authenticator class="com.atlassian.crowd.integration.seraph.JIRAAuthenticator"/>
```

2.3 Enable JIRA's 'External User Management'

Once the setup is complete, you can configure JIRA to allow external user management. Go to the JIRA Administration Console. In the General Configuration section, turn 'External user management' and 'External password management' on or off. (See the JIRA Administrator's Guide for details).

JIRA with external user management ON:

This is recommended, because it allows you to use Crowd's powerful cross-directory user administration features.

Crowd allows you to automatically assign new users to groups. You can define default groups for each directory. Every new user automatically becomes a member of these groups.

If you turn external user management on, the following functions can no longer be performed from within the JIRA administration interface: adding users, adding groups, editing users, editing groups.

If you are using Crowd 1.1.1 or earlier, you must turn external user management on in JIRA.

JIRA with external user management OFF:

The "External User Management" option does not impact the Crowd integration. It just displays or hides UI options in JIRA.

This means that you can allow signup via JIRA, and you can manage your users within JIRA. Changes will flow through to Crowd.

JIRA has an automatic group membership feature. This means that any new user added through JIRA will automatically be a member of all groups which have the JIRA Users permission. In this way, you can ensure that a new user is automatically added to several groups when they sign up with JIRA.

Any group or user changes will cascade to all directories assigned to the JIRA application in Crowd. For example, if user 'jbloggs' registers in JIRA, 'jbloggs' will be added to every Crowd directory linked with the JIRA application.

2.4 (Optional) Tune the Cache

Enabling caching on the Crowd server: When using the Atlassian-User and Crowd framework together with JIRA, it is highly recommended that caching be enabled on the Crowd server. Multiple redundant calls to the Atlassian-User framework are made on any given request. These results can be stored locally between calls by enabling caching via the Crowd Options menu. Note that this caching on the Crowd server is enabled by default.

Enabling application caching for JIRA: If application caching is enabled for JIRA, JIRA will obtain all necessary information for the period specified by the cache configuration. See Configuring Caching for an Application. If a change or addition occurs to Crowd users, groups and roles, these changes will not be visible in JIRA until the cache expires for that specific item, i.e. for the particular user, group or role.

From JIRA 3.13, the default cache is two hours. In earlier versions, the default value for the application cache is 5 minutes (300 seconds) — increasing this to one or two hours (3600 or 7200 seconds) will improve the performance of your JIRA site.

2.5 (Optional) Disable the Auto-Complete Function in JIRA's User Picker

To improve performance on page-loading in JIRA, we recommend that you disable the auto-complete function in JIRA's 'User Picker' popup screens. Follow the instructions in the JIRA documentation.

More information: In our experience, disabling this feature in JIRA helps performance for customers with extremely large user bases. If you leave this feature enabled and have adequate performance results in JIRA, feel free to leave it enabled.

See Crowd in Action

You should now be able to login using users belonging to the jira-users group. Try adding a user to the group using Crowd — you should be able to login to JIRA using this newly created user. That's centralised authentication in action!
If you have enabled SSO, you can try adding the JIRA Directory in Crowd and jira-administrators group to the crowd application (see Mapping a Directory to an Application and Specifying which Groups can access an Application). This will allow JIRA administrators to log in to the Crowd Administration Console. Try logging in to Crowd as a JIRA administrator, and then point your browser at JIRA. You should be logged in as the same user in JIRA. That's single sign-on in action!

Known Limitations

A problem occurs in JIRA if a user is removed after that user has participated in an issue i.e. if JIRA refers to the user. If the user is internally managed by JIRA, JIRA will prevent the removal of the user but if the user is managed by an external system such as Crowd, JIRA will throw a DataAccessException.

The current workaround for this is to deactivate the user's account (by removing them from the jira-users group). This issue can be tracked here: http://jira.atlassian.com/browse/CWD-202

Child pages