Documentation for Crowd 2.4. Documentation for other versions of Crowd is available too.
Currently Crowd supports centralised authentication and single sign-on for JIRA versions 3.7.4 and later.
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:
Please ensure that your Crowd and JIRA versions are compatible:
Do not deploy multiple Atlassian applications in a single Tomcat container.
There are also a number of practical reasons why we do not support deploying multiple Atlassian applications in a single Tomcat container. Firstly, you must shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in that Tomcat container will be inaccessible.
Finally, we recommend not deploying any other applications to the same Tomcat container that runs Crowd, especially if these other applications have large memory requirements or require additional libraries in Tomcat's lib
subdirectory.
CROWD
.JIRA
. For the purposes of this document, we will assume that you have used the 'Crowd distribution (not EAR-WAR)' (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.
jira-users
jira-developers
jira-administrators
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.
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.
JIRA/atlassian-jira/WEB-INF/classes/crowd.properties
file. (See Step 2 below.)
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.
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.
The instructions for step 2 below apply to JIRA 4.3 or newer. If you use JIRA 4.2 or older, please follow "Step 2" on Integrating Crowd with Atlassian JIRA 4.2 or earlier instead.
JIRA can use Crowd for user authentication simply by adding 'Atlassian Crowd' as user directory.
For more information on configuring a Crowd directory in JIRA, check out the JIRA documentation on Connecting to Crowd or Another JIRA Server for User Management.
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.
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/atlassian-jira/WEB-INF/classes/seraph-config.xml
file. Comment out the authenticator
node:
<!--<authenticator class="com.atlassian.jira.security.login.JiraSeraphAuthenticator"/>-->
Uncomment the line that contains the new authenticator:
<authenticator class="com.atlassian.jira.security.login.SSOSeraphAuthenticator"/>
crowd.properties
file from CROWD/client/conf/
to JIRA/atlassian-jira/WEB-INF/classes
.Edit JIRA/atlassian-jira/WEB-INF/classes/crowd.properties
. Change the following properties:
Key | Value |
---|---|
application.name |
|
application.password | The password must match the one that you specified when you defined the application in Crowd (see Step 1 above). |
application.login.url | This should be set to the base URL of your JIRA server. Crowd will redirect users here if they need to authenticate. |
crowd.base.url | http://localhost:8095/crowd/ |
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. |
It is possible to define multiple user directories in JIRA. However, if you enable SSO integration, you will only be able to authenticate as users from the Crowd server defined in the crowd.properties
file.
You can read more about optional settings in the crowd.properties file.
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.
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!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!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