3.2.4 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. More about the OSUser API can be reviewed at http://www.opensymphony.com/osuser/.

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

Prerequisites

1. Download and install Crowd. Refer to the Crowd installation guide for detailed information on how to do this. We will refer to the Crowd root folder as CROWD.
2. Download and install JIRA (version 3.7.4 or later). Refer to the JIRA installation guide for detailed information on how to do this. We will refer to the JIRA root folder as JIRA. For the purposes of this document, we will assume that the 'standalone' (i.e. the easier and recommended) installation method of JIRA has been used. If you need to install JIRA as an EAR/WAR, simply explode the EAR/WAR and make the necessary changes as described below, and repackage the EAR/WAR.
3. Make sure JIRA is not running when 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. For information on how to do this, see 2.2 Adding a Directory. We will assume that the directory is called JIRA Directory 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 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:

1. jira-users
2. jira-developers
3. jira-administrators

You also need to ensure that the JIRA Directory 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 (principals) into Crowd, use the JIRA Importer tool by navigating to Principals > Import Users > JIRA. Select the JIRA Directory as the directory into which JIRA users will be imported. For details please see 2.4.2 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 principal in the JIRA Directory and add them to the three JIRA-specific groups (above). The Crowd documentation has more information on creating groups,  creating principals and assigning principals to groups.

1.2 Define the JIRA Application in Crowd

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.

1. Log in to the Crowd Administration Console and navigate to Applications > Add Application.
2. Fill out the form to add the JIRA application:
   
   

The Name and Password values must match the application.name and application.password that you set in the JIRA/atlassian-jira/WEB-INF/classes/crowd.properties (see Step 2 below).

1.3 Specify which users can log in to JIRA

Now that Crowd is aware of the JIRA application, Crowd needs to know which directories or users can authenticate (log in) via Crowd. 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 to authenticate:

• Only principals who are members of the jira-users group will be able to authenticate against JIRA.
• Only principals who are members of the jira-administrators group will be able to use the JIRA administration console.

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

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

Please see 3.5 Specifying an Application's Address or Hostname. Please note:

• If JIRA is on a different host to Crowd
  If you are running the JIRA on a different host to Crowd, you will need to modify the permissible hosts via the Remote Addresses tab. This lists the hosts/IP addresses that are allowed to authenticate to Crowd. If JIRA is remote to Crowd, add the IP address of your JIRA server and ensure the "Status" field is set to "true". Remove the entry for localhost.

• If JIRA is on the same host as Crowd
  By default, when you add an application, localhost is a permissible foreign host. However, you will also need to manually add the IP address 127.0.0.1, as incoming requests to Crowd from JIRA (both on the same, local, host) may be from the host 127.0.0.1 and not localhost. Crowd does not do a DNS lookup of the hostname, rather, it compares the values as is. Ensure the "Status" field is set to "true".
  

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.

1. Copy the Crowd client libraries and configuration files to JIRA (this is described in the Client Configuration documentation). This is summarised below:

   Copy From	Copy To
   CROWD/client/*.jar	JIRA/atlassian-jira/WEB-INF/lib
   CROWD/client/conf/crowd.properties	JIRA/atlassian-jira/WEB-INF/classes

   There is no need to copy across anything from CROWD/client/lib. All the required libraries from there already exist in JIRA versions 3.7.4 and later.
2. Edit JIRA/atlassian-jira/WEB-INF/classes/crowd.properties. Change the following properties:

   Key	Value
   application.name	jira
   application.password	set a password
   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. The application.name and application.password must match the Name and Password that you specified when you defined the application in Crowd (see Step 1 above). All other attributes of the crowd.properties file are not used by JIRA.

2.2 Configure JIRA to use Crowd's Authenticator

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

1. 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>
   

   
   
2. View JIRA/atlassian-jira/WEB-INF/classes/propertyset.xml. If an entry doesn't exists for the CrowdPropertySet, to add the following <propertyset> at the end of the file as the last <propertyset>:

   <propertyset name="crowd" class="com.atlassian.crowd.integration.osuser.CrowdPropertySet"/>
   

3. At this stage, JIRA is set up for centralised authentication. If you wish to enable single sign-on (SSO) to JIRA, edit JIRA/atlassian-jira/WEB-INF/classes/seraph-config.xml. Change the authenticator node to read:

   <authenticator class="com.atlassian.crowd.integration.seraph.JIRAAuthenticator"/>
   

   JIRA's authentication and access request calls will now be performed using Seraph. Now when authentication or access request calls are performed versus the OSUser framework, the JIRA stack will call the Crowd providers and propertyset implementations.

2.3 Enable JIRA's 'External User Management'

Once the setup is complete, go to the JIRA Administration Console. In the General Configuration section, turn on 'External User Management' and 'External Password Management' (see the JIRA Administrator's Guide for details). This means that the following functions can no longer be performed from within the JIRA administration interface: adding users, adding groups, editing users, editing groups.

See Crowd in Action

• You should now be able to login using principals belonging to the jira-users group. Try adding a principal to the group using Crowd — you should be able to login to JIRA using this newly created principal. That's centralised authentication in action!
• If you have enabled SSO, you can try adding the JIRA Directory and jira-administrators group to the crowd application (see 3.3 Mapping a Directory to an Application and 3.4 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 principal in JIRA. That's single sign-on in action!

Known Limitations

• JIRA currently does not have logic to handle the removal of a user when external user management is enabled. If the user is removed in Crowd, JIRA will throw a DataAccessException. The current workaround for this is to deactivate the principal's account (by removing them from the jira-users group). This issue can be tracked here: http://jira.atlassian.com/browse/CWD-202

Related Topics  

• 3.1 Using the Application Browser
• 3.2 Adding an Application
  • 3.2.1 Integrating Crowd with Apache
  • 3.2.2 Integrating Crowd with Atlassian Bamboo
  • 3.2.3 Integrating Crowd with Atlassian Confluence
  • 3.2.4 Integrating Crowd with Atlassian JIRA
  • 3.2.5 Integrating Crowd with Cenqua FishEye
  • 3.2.6 Integrating Crowd with Jive Forums
    • 3.2.6.1 Jive SSO
  • 3.2.7 Integrating Crowd with a Custom Application
• 3.3 Mapping a Directory to an Application
  • 3.3.1 Specifying the Directory Order for an Application
• 3.4 Specifying which Groups can access an Application
• 3.5 Specifying an Application's Address or Hostname
• 3.6 Managing an Application's Session
• 3.7 Deleting or Deactivating an Application

Crowd 1.0 Documentation