3.2.3 Integrating Crowd with Atlassian Confluence

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.

Currently Crowd supports centralised authentication and single sign-on for Confluence versions 2.3 and later.

If you are running Confluence version 2.4.4 or earlier, you will need to upgrade the confluence/WEB-INF/lib/atlassian-user-XXXX-XX-XX.jar Atlassian User library to version 2007-04-05. The original library file will need to be backed up, removed, and then replaced with the new version.

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 Confluence (version 2.3 or later). Refer to the Confluence installation guide for detailed information on how to do this. We will refer to the Confluence root folder as CONFLUENCE. For the purposes of this document, we will assume that the standalone (ie. the easier) installation method of Confluence has been used. If you need to install Confluence as an EAR/WAR, simply explode the EAR/WAR and make the necessary changes as described below, and repackage the EAR/WAR.
3. After Confluence is set up, make sure Confluence is not running when 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 2.2 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:

1. confluence-users
2. 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. You can either:

• If you have an existing Confluence deployment and would like to import existing users (principals) and groups into Crowd, use the Confluence Importer tool by navigating to Principals > Import Users > Confluence. Select the Confluence Directory as the directory into which Confluence users will be imported. For details please see 2.4.1 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 principal in the Confluence Directory and assign them to both the confluence-users and confluence-administrators group. 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 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:

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

   Attribute	Description
   Name	The username which the application will use when it authenticates against the Crowd framework as a client. This value must be unique, i.e. it cannot be used by more than one application client.
   Description	A short description of the application. Note: a web URL is often helpful.
   Active	Only deselect this if you wish to prevent all users (from all directories) from accessing this application.
   Password	The password which the application will use when it authenticates against the Crowd framework as a client.
   Default Directory	A directory that contains relevant users. Note: additional directories can be added later.

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

1.3 Specify which users can log in to Confluence

Now that Crowd is aware of the Confluence application, Crowd needs to know which users can authenticate (log in) to Confluence via Crowd. 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 3.4 Specifying which Groups can access an Application.

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

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

• If Confluence is on a different host to Crowd
  If you are running the Confluence 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 Confluence is remote to Crowd, add the IP address of your Confluence server and ensure the "Status" field is set to "true". Remove the entry for localhost.

• If Confluence 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 Confluence (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 Confluence to talk to Crowd

2.1 Install the Crowd Client Libraries into Confluence

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

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

   Copy From	Copy To
   CROWD/client/*.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 there already exist in Confluence versions 2.3 and later.

2. This step only applies if you are using Confluence 2.5.6 or later:
   Copy the file crowd-integration-bamboo-1.1.1.jar from here:
   http://confluence.atlassian.com/download/attachments/198785/crowd-integration-bamboo-1.1.1.jar?version=1
   to here:
   CONFLUENCE/confluence/WEB-INF/lib
3. Edit CONFLUENCE/confluence/WEB-INF/classes/crowd.properties. Change the following properties:

   Key	Value
   application.name	confluence
   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 defining the application in Crowd (see Step 1 above).

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. This sub-step applies to Confluence 2.5.5 and earlier only:
   Edit the CONFLUENCE/confluence/WEB-INF/classes/atlassian-user.xml file and uncomment the following:

   <repository key="crowd" class="com.atlassian.crowd.integration.atlassianuser.CrowdRepository">
     <classes>
       <processor>com.atlassian.crowd.integration.atlassianuser.CrowdRepositoryProcessor</processor>
       <userManager>com.atlassian.crowd.integration.atlassianuser.CrowdUserManager</userManager>
       <groupManager>com.atlassian.crowd.integration.atlassianuser.CrowdGroupManager</groupManager>
       <authenticator>com.atlassian.crowd.integration.atlassianuser.CrowdAuthenticator</authenticator>
       <propertySetFactory>com.atlassian.crowd.integration.atlassianuser.CrowdPropertySetFactory</propertySetFactory>
       <entityQueryParser>com.atlassian.crowd.integration.atlassianuser.CrowdEntityQueryParser</entityQueryParser>
     </classes>
   </repository>

2. This sub-step applies to Confluence 2.5.6 and later only:
   Edit the CONFLUENCE/confluence/WEB-INF/classes/atlassian-user.xml file and add the following new entry:

   <crowd key="crowd" name="Crowd Repository"/>

3. You will need to comment out the other repositories, eg:

   <!-- <osuser key="osuserRepository" name="OSUser Repository"/> -->
   <!-- <hibernate name="Hibernate Repository" key="hibernateRepository"  description="Hibernate Repository" /> -->

   This will tell Confluence to use Crowd's user repository for user management.
   

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

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

   Confluence's authentication and access request calls will now be performed using Seraph.

2.3 Enable Confluence's 'External User Management'

Once the setup is complete, you may optionally wish to enable a Confluence feature known as 'External User Management', to prevent Confluence administrators from creating/modifying principals. For more information please see the Confluence documentation regarding External User Management.

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

See Crowd in Action

• You should now be able to login using principals belonging to the confluence-users group. Try adding a principal to the group using Crowd — you should be able to login to Confluence using this newly created principal. 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 3.3 Mapping a Directory to an Application and 3.4 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 principal in Confluence. That's single sign-on in action!

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