This document contains notes on upgrading an existing Crowd installation to Crowd 2.1. You can see the features of this release in the Crowd 2.1 Release Notes.

On this page:

Upgrade Notes

Please read the following sections and take action where the note applies to your Crowd installation, before upgrading to the new release of Crowd.

Upgrade to Crowd 2.1.1 for Compatibility with JDK 1.5

If you are planning to upgrade to Crowd 2.1, please upgrade directly to Crowd 2.1.1 or upgrade your JDK to 1.6.

Crowd 2.1 is not compatible with JDK 1.5. This problem is fixed in Crowd 2.1.1.

LDAP Caching Disabled by Default on Upgrade – Please Enable If Required

As described in the release notes, Crowd 2.1 introduces database-backed caching for all LDAP directories. For new directory connectors, caching is enabled by default. When you upgrade to Crowd 2.1, caching is disabled by default for existing directories.

Note: We have optimized the database caching for directories containing approximately 10 000 (ten thousand) users. If your directory is significantly larger, the new caching may not be as beneficial. For very large user bases, we recommend that you leave the caching disabled.

To take advantage of the new caching for your existing LDAP directories, please:

• Enable the cache for each directory on the directory connector's 'Details' tab.
• Set the polling interval on the 'Connector' tab. See Configuring Caching for an LDAP Directory.

Changed Authorization Behavior when Multiple Directories are Mapped to an Application

We have changed the way Crowd checks for group memberships when there is more than one directory mapped to an application.

Note: This change affects only those configurations that have duplicate usernames across directories and multiple directories mapped to a single application.

In previous versions of Crowd, authentication was done on the first directory that contained the username but group memberships were aggregated across directories. In more detail:

• For user authentication, Crowd searched the directories in the order specified per application and used the credentials of the first occurrence of the user.
• When granting the user access to an application based on group membership, Crowd amalgamated the group memberships in all the directories where the username occurred.
• See the details per operation in Crowd 2.0: Understanding How Crowd Manages Multiple Directories.

In Crowd 2.1 and later, authentication is done on the first directory that contains the username and group memberships for the user are obtained from the same directory. In more detail:

• For user authentication the behavior is unchanged, as described above.
• When granting the user access to an application based on group membership, Crowd will look for group membership only in the first directory where the username appears, based on the order of directories mapped to the application.
• See the details per operation in Crowd 2.1: Understanding How Crowd Manages Multiple Directories.

What you need to do: Please check the order in which your directories are mapped to each application. See Specifying the Directory Order for an Application.

Active/Inactive Setting on Directories Now Effective

In previous versions of Crowd, the 'Active' setting on the directory connector 'Details' tab had no effect. In Crowd 2.1, this setting is now effective for all directory types. For example, see the documentation on configuring an internal directory. If a directory is not marked as 'Active', it is inactive.

Inactive directories:

• are not included when searching for users, groups or memberships.
• are still displayed in the Crowd Administration Console screens.

Upgrading Apache and Subversion Connectors

With Crowd 2.1, there is an improved version of the Apache/SVN connector. See the release notes for details of the improvements. To make use of the new version of the connectors, you will need to update your configuration. Follow these instructions to disable any previous versions of the connector before proceeding. See 2018-04-24_10-55-25_Integrating Crowd with Apache for full instructions.

Note that existing Apache/SVN connectors will also work with Crowd 2.1. This means there is no need to upgrade the connectors until you are ready. If you do not upgrade, you will not benefit from the improvements offered by the new connectors.

Plugin Dependencies Need Updating from 'crowd-plugins' to 'crowd-server'

This section is of interest to plugin developers with existing Crowd plugins. We have refactored crowd-plugins to crowd-server. If you have added an explicit dependency in your plugin to crowd-plugins, you will need to change the dependency to crowd-server.

Upgrading Custom Application Connectors

If you are using a custom application connector, please note the following points:

• You can connect a Crowd 2.0.7 client to the Crowd 2.1 server, because the SOAP API is fully backward-compatible.
• We recommend that you upgrade the client to version 2.1, which makes use of the new REST API. This will require a recompilation of the application, because some of the classes have moved into different packages within the client JAR.

Changed API for Event Listener Plugins

In Crowd 2.1 and later, Crowd events are annotation-based. This means that you must write annotation-based event listeners, using the com.atlassian.event.api.EventListener annotation on your methods. Implementing the com.atlassian.event.EventListener interface is no longer supported. 

Early Prototype REST API No Longer Available

Crowd 2.0 introduced an experimental REST API, named 'admin', which allowed interactions with the Crowd Administration Console. This API is no longer available. It has been replaced in Crowd 2.1 by a new set of 'usermanagement' REST APIs for use by applications connecting to Crowd.

Please refer to the release notes for a summary of the functionality available in the new REST APIs.

The following functions were available in the Crowd 2.0 REST APIs, but will not be available in the new REST APIs:

• Retrieving a list of directories.
• Retrieving basic directory information.
• Executing operations per directory. You can mimic this by creating an application that maps only to the desired directory.

Roles in Crowd are Deprecated

As previously announced, roles are now deprecated in Crowd. We have not changed the functionality of roles in Crowd 2.1, but we do recommend that you move away from the use of roles in your Crowd installation so that you will not be adversely affected by the planned redesign of role functionality. Roles are disabled by default when you create a new LDAP directory.

At present, the implementation of roles in Crowd is identical to the implementation of groups. This design does not provide much useful functionality, so we are planning to redesign the way Crowd supports roles. If you would like to help us to design better role-based access control, please add a comment to the improvement request CWD-931, letting us know how you would like to see it work.

Crowd Now Runs in the Background

We have changed the Crowd startup scripts (start_crowd.bat and start_crowd.sh) to run Crowd in the background. We have also added new scripts to stop Crowd: stop_crowd.bat and stop_crowd.sh.

Note that on OS X and Linux, you can no longer use Ctrl-C to stop the Crowd server – use the stop_crowd.sh script instead. On Windows a second command window pops up when you start Crowd, and you can use Ctrl-C in that window to stop Crowd.

Upgrade Procedure

To upgrade to Crowd 2.1.x from 2.0.x or earlier, please follow these upgrade instructions.