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 application, which is an exploded WAR stored in CONFLUENCE/confluence.

1. If you are using the Crowd WAR distribution, then you will need to get the CROWD client libraries from the Crowd distribution, available on our download site.
2. If you are using the Windows Evaluation distribution of Confluence, please see this page on how to update the crowd.properties file in Confluence.

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

4. Replace Confluence's cache configuration file:

   Copy From	Replace File
   CROWD/client/conf/crowd-ehcache.xml	CONFLUENCE/confluence/WEB-INF/classes/crowd-ehcache.xml

5. 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 to the required number of minutes between validation requests. The recommended default is 2 minutes. Setting this value to 1 or higher will increase the performance of Crowd's integration. Setting this value to 0 will cause the application to perform authentication checks on each request but can cause poor performance, especially with Crowd 2.1 - Crowd 2.3.2 using REST due to CWD-2646.

   
   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.

1. Edit the CONFLUENCE/confluence/WEB-INF/classes/atlassian-user.xml file so that the content of the file is:

   <atlassian-user>
       <repositories>
   
           <crowd key="crowd" name="Crowd Repository"/>
   
       </repositories>
   </atlassian-user>
   

   Make sure the content of the file is only what is indicated above, otherwise you may get this error

2. At this stage, Confluence is set up for centralized 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:

   Edit the CONFLUENCE/confluence/WEB-INF/classes/seraph-config.xml file. Comment out the authenticator node:

   <!--<authenticator class="com.atlassian.confluence.user.ConfluenceAuthenticator"/>-->
   

   
   Add a new authenticator, choosing the one relevant to your version of Confluence:

   • If you are using Confluence 3.4 or later:

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

   • If you are using Confluence 3.3.3 or earlier:

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

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