This page last changed on Oct 19, 2010 by lamendes.
Atlassian's popular Confluence wiki can quickly be configured to use the atlassian-user libraries to link in single or multiple directory servers through Crowd.
On this page:
 | If you are using NTLM for Windows authentication, you may want to read about configuring Crowd's Confluence NTLM plugin for single sign-on. |
Compatibility of Confluence and Crowd Versions
For best performance and support, please ensure that your Crowd and Confluence versions are compatible:
- Crowd versions 1.2 and later support Confluence 2.6.2 and later.
- This version of Crowd does not support Confluence 2.6.1 or earlier.
- If you are using Confluence 2.8 or later, please upgrade to Crowd 1.3.2 or later.
Explanation: With Confluence 2.8 the atlassian-user interface has changed, and Crowd 1.3.2 provides the required update to Crowd's atlassian-user integration module.
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 Confluence (version 2.6.2 or later). Refer to the Confluence installation guide for instructions. We will refer to the Confluence root folder as CONFLUENCE. For the purposes of this document, we will assume that you have used the Standalone (i.e. the easier) installation method of Confluence. If you need to install Confluence as an EAR/WAR, simply explode the EAR/WAR and make the necessary changes as described below, then repackage the EAR/WAR.
- Run the Confluence Setup Wizard, as described in the Confluence documentation. During this setup process, you will define the Confluence administrator's username and password. It is easier to do this before you integrate Confluence with Crowd.
- After setting up Confluence, shut down Confluence before you begin the integration process described below.
Step 1. Configuring Crowd to Talk to Confluence
1.1 Prepare Crowd's Directories/Groups/Users for Confluence
The Confluence application will need to authenticate users against a directory configured in Crowd. You will need to set up a directory in Crowd for Confluence. For more information on how to do this, see Adding a Directory. We will assume that the directory is called Confluence 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 Confluence Directory to house Confluence users.
Confluence also requires particular groups to exist in the directory in order to authenticate users. You will need to create two groups in the Confluence Directory:
- confluence-users
- confluence-administrators
See the documentation on Creating Groups for more information on how to define these groups.
You also need to ensure that the Confluence Directory contains at least one user who is a member of both groups. Choose one of the two options below:
- If you have an existing Confluence deployment and would like to import existing users and groups into Crowd, use the Confluence Importer tool by navigating to Users > Import Users > Atlassian Importer. Select 'Confluence' as the Atlassian product, and the Confluence Directory as the directory into which Confluence users will be imported. For details please see Importing Users from Atlassian Confluence.
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 Confluence users, make sure you use Crowd to create at least one user in the Confluence Directory and assign them to both the confluence-users and the confluence-administrators group. The Crowd documentation has more information on creating groups, creating users and assigning users to groups.
1.2 Define the Confluence Application in Crowd
Crowd needs to be aware that the Confluence application will be making authentication requests to Crowd. We need to add the Confluence application to Crowd and map it to the Confluence Directory:
- Log in to the Crowd Administration Console and navigate to Applications > Add Application.
- Complete the 'Add Application' wizard for the Confluence 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 CONFLUENCE/confluence/WEB-INF/classes/crowd.properties file. (See Step 2 below.)
1.3 Specify which Users can Log In to Confluence
Once Crowd is aware of the Confluence application, Crowd needs to know which users can authenticate (log in) to Confluence 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 confluence-users and confluence-administrators groups within the Confluence Directory to authenticate:

For details please see Specifying which Groups can access an Application.
1.4 Specify the Address from which Confluence can Log In to Crowd
As part of the 'Add Application' wizard, you will set up Confluence's IP address. This is the address which Confluence 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 Confluence to Talk to Crowd
2.1 Install the Crowd Client Library into Confluence
Confluence needs Crowd's client library and configuration file in order to be able to delegate user authentication to the Crowd application. As stated earlier, we will modify the Confluence application by editing the standalone application, which is an exploded WAR stored in CONFLUENCE/confluence.
- 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.
- If you are using the Windows Evaluation distribution of Confluence, please see this page on how to update the crowd.properties file in Confluence.
- Copy the Crowd client library and configuration file to Confluence:
Copy From |
Copy To |
CROWD/client/crowd-integration-client-X.X.X.jar |
CONFLUENCE/confluence/WEB-INF/lib |
CROWD/client/conf/crowd.properties |
CONFLUENCE/confluence/WEB-INF/classes |
There is no need to copy across anything from CROWD/client/lib. All the required libraries from that directory already exist in Confluence versions 2.3 and later.
 | Be sure that there is only one crowd-integration-client-x.x.x.jar file in the lib directory. Otherwise, it would cause library incompatibilities. |
A note about older Confluence versions:
Confluence 2.5.6 to 2.6.1 are not compatible with Crowd 1.2 and later. We recommend that you upgrade to Confluence 2.6.2 or later. If you can not upgrade your Confluence instance, you will need to remove the seraph-X.X.X.jar file from Confluence's <CONFLUENCE-INSTALLATION>/confluence/WEB-INF/lib/seraph-X.X.X.jar and replace it with the following file:
http://repository.atlassian.com/maven2/com/atlassian/seraph/atlassian-seraph/0.10/atlassian-seraph-0.10.jar.
- Replace Confluence's cache configuration file:
Copy From |
Replace File |
CROWD/client/conf/crowd-ehcache.xml |
CONFLUENCE/confluence/WEB-INF/classes/crowd-ehcache.xml |
- Edit CONFLUENCE/confluence/WEB-INF/classes/crowd.properties. Change the following properties:
Key |
Value |
application.name |
confluence
The application.name and application.password must match the Name and Password that you specified when defining the application in Crowd (see Step 1 above). |
application.password |
The application.name and application.password must match the Name and Password that you specified when defining 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 |
This is the number of minutes between validation requests, when Crowd validates whether the user is logged in to or out of the Crowd SSO server. Set this value to 0 if you want authentication checks to occur on each request. Otherwise set to the required number of minutes between validation requests. 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 Confluence to use Crowd's Authenticator
Now that the Crowd client libraries exist, we need to configure Confluence to use them.
- Edit the CONFLUENCE/confluence/WEB-INF/classes/atlassian-user.xml file so that the content of the file is:
Make sure the content of the file is only what is indicated above, otherwise you may get this error
- At this stage, Confluence is set up for centralised authentication. If you wish to enable single sign-on (SSO) or if you are using Confluence 3.2.1 or later, take the following steps to ensure that Confluence's authentication and access request calls will be performed using Seraph:
Skip this step if you are using the Confluence NTLM plugin to enable SSO. Instead, follow the instructions on configuring Confluence for NTLM SSO.
Edit the CONFLUENCE/confluence/WEB-INF/classes/seraph-config.xml file. Comment out the authenticator node:
Add a new authenticator, choosing the one relevant to your version of Confluence:
- If you are using Confluence 3.4 or later:
- If you are using Confluence 3.3.3 or earlier:
2.3 Enable Confluence's External User Management
Once the setup is complete, you may wish to turn 'External User Management' on in Confluence. This will prevent Confluence administrators from being able to add or update users. For more information please see the Confluence documentation regarding External User Management.
Note:
- If you are using Confluence 2.6.2 or earlier, this step is required i.e. you must turn on external user management in Confluence.
- If your Crowd directory permissions are configured so that Confluence cannot update the Crowd directories, this step is required i.e. you must turn on external user management in Confluence. Otherwise, an error will occur when Confluence attempts to write data into Crowd.
- If you have imported Confluence users into Crowd, you may want to delay turning on 'External User Management' for a week or two, to give users time to reset their passwords. (Because users' passwords are encrypted in Confluence's database, they will not be copied across to Crowd.)
2.4 (Optional) Tune the Cache
Enabling caching on the Crowd server: When using the Atlassian-User and Crowd framework together with Confluence, 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 Confluence: If application caching is enabled for Confluence, Confluence 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 Confluence until the cache expires for that specific item, i.e. for the particular user, group or role.
The default period for the application cache is 5 minutes (300 seconds). To increase the performance of your application, consider changing the cache value to one or two hours (3600 or 7200 seconds).
See Crowd in Action
- Users belonging to the confluence-users group should now be able to log in to Confluence.
- Try adding a user to the confluence-users group using Crowd — you should be able to log in to Confluence using this newly created user. That's centralised authentication in action!
- If you have enabled SSO, you can try adding the Confluence Directory and confluence-administrators group to the crowd application (see Mapping a Directory to an Application and Specifying which Groups can access an Application). This will allow Confluence administrators to log in to the Crowd Administration Console. Try logging in to Crowd as a Confluence administrator, and then point your browser at Confluence. You should be logged in as the same user in Confluence. That's single sign-on in action!
RELATED TOPICS
Crowd Documentation
|