3.2.08 Integrating Crowd with Atlassian Bamboo

Atlassian's Bamboo integration server 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 Bamboo versions 1.2.2 and later.

Due to incompatible atlassian-user libraries, Bamboo releases prior to 1.2.2 are not compatible with latest version of Crowd. We recommend that you upgrade to the latest version of Bamboo before attempting to integrate Crowd.

Prerequisites

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.
Download and install Bamboo (version 1.2.2 or later). Refer to the Bamboo Installation Guide for detailed information on how to do this. We will refer to the Bamboo root folder as BAMBOO. For the purposes of this document, we will assume that you have used the Standalone (ie. the easier) installation method of Bamboo. If you need to install Bamboo as an EAR/WAR, simply explode the EAR/WAR and make the necessary changes as described below, and repackage the EAR/WAR.
After Bamboo is set up, make sure Bamboo is not running when you begin the integration process described below.

Step 1. Configuring Crowd to Talk to Bamboo

1.1 Prepare Crowd's Directories/Groups/Users for Bamboo

The Bamboo application will need to authenticate users against a directory configured in Crowd. You will need to set up a directory in Crowd for Bamboo. For more information on how to do this, see 2.2 Adding a Directory. We will assume that the directory is called Bamboo 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 Bamboo Directory to house Bamboo users.

Bamboo also needs an administrative group to exist in the directory in order to access the administration features. You will need to create two groups in the Bamboo Directory:

bamboo-admin
bamboo-user (optional)

See the documentation on Creating Groups for more information on how to define these groups.

You also need to ensure that the Bamboo Directory contains at least one user who is a member of both groups. You can either:

If you have an existing Bamboo deployment and would like to import existing users (principals) and groups into Crowd, use the Bamboo Importer tool by navigating to Principals > Import Users > Bamboo. Select the Bamboo Directory as the directory into which Bamboo users will be imported. For details please see 2.4.5 Importing Users from Atlassian Bamboo. 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 Bamboo users, make sure you use Crowd to create at least one principal in the Bamboo Directory and assign the principal(s) to both the bamboo-user and the bamboo-admin groups. The Crowd documentation has more information on creating groups, creating principals and assigning principals to groups.

1.2 Define the Bamboo Application in Crowd

Crowd needs to be aware that the Bamboo application will be making authentication requests to Crowd. We need to add the Bamboo application to Crowd and map it to the Bamboo Directory:

Log in to the Crowd Administration Console and navigate to Applications > Add Application.

Complete the form to add the Bamboo application:

属性	説明
名前	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.
説明	A short description of the application. Note: A web URL is often helpful.
アクティブ	Only deselect this if you wish to prevent all users (from all directories) from accessing this application.
パスワード	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 Bamboo/webapp/WEB-INF/classes/crowd.properties (see Step 2 below).

1.3 Specify which Users can Log in to Bamboo

Now that Crowd is aware of the Bamboo application, Crowd needs to know which users can authenticate (log in) to Bamboo via Crowd. You can either allow entire directories to authenticate, or just particular groups within the directories. In our example, we will allow the bamboo-user and bamboo-admin groups within the Bamboo Directory to authenticate:

If you are not using a bamboo-user group as a security restriction, you will need to set 'Allow all to authenticate' to 'true' when mapping the directory, otherwise only bamboo-admin group members will be able to log in to Bamboo.

1.4 Specify the Address from which Bamboo can Log in to Crowd

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

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

If Bamboo 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 Bamboo (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 Bamboo to Talk to Crowd

If your Bamboo version is earlier than 1.2.2, please upgrade to the latest stable version of Bamboo.

2.1 Install the Crowd Client Libraries into Bamboo

Bamboo 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 modify the Bamboo application by editing the standalone application, which is an exploded WAR stored in BAMBOO/webapp.

Copy the Crowd client libraries and configuration files to Bamboo. This is described in the Client Configuration documentation. Below is a summary:

Copy From	Copy To
CROWD/client/crowd-core-x.x.x.jar	BAMBOO/webapp/WEB-INF/lib
CROWD/client/crowd-atlassian-user-x.x.x.jar	BAMBOO/webapp/WEB-INF/lib
CROWD/client/conf/crowd.properties	BAMBOO/webapp/WEB-INF/classes

Bamboo 1.2.4 release is not compatible with Crowd.
You will need to remove the following file from Bamboo's WEB-INF/lib/seraph-0.7.23.jar directory and replace it with the following:
http://repository.atlassian.com/maven2/com/atlassian/seraph/atlassian-seraph/0.9/atlassian-seraph-0.9.jar

Note that Bamboo 2.0 Beta is compatible with Crowd, and you don't need to replace the Seraph jar.

BAMBOO/webapp/WEB-INF/classes/crowd.properties を編集します。次のプロパティを変更します。

キー	値
application.name	bamboo
application.password	set a password
crowd.server.url	http://localhost:8095/crowd/services/
session.validationinterval	Set to 0, if you want authentication checks to occur on each request. Otherwise set to the number of minutes between requests 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.

If your Crowd server's port is configured differently from the default (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). Bamboo does not use any of the other attributes of the crowd.properties file.

2.2 Configure Bamboo to use Crowd's Authenticator

Now that the Crowd client libraries exist, we need to configure Bamboo to use them.

Edit the Bamboo/webapp/WEB-INF/classes/atlassian-user.xml file so that the contents of the file is:

<atlassian-user>
    <repositories>

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

At this stage, Bamboo is set up for centralised authentication. If you wish to enable single sign-on (SSO) to Bamboo, edit BAMBOO/webapp/WEB-INF/classes/seraph-config.xml. Comment out the authenticator node :
```

```
and add a new one:
```
<authenticator class="com.atlassian.crowd.integration.seraph.BambooAuthenticator"/>
```
Bamboo's authentication and access request calls will now be performed using Seraph.

2.3 Configure External User Management in Bamboo

For Bamboo to integrate successfully with Crowd, Bamboo's 'External User Management' option needs to be:

Checked if you are using an LDAP directory with Crowd and you don't have write-access in LDAP.
Unchecked if you are using internal Crowd directories, or Crowd with LDAP where you do have write-access.

詳細情報:

Please ignore the wording on some versions of the Bamboo screens, which may imply that you should check this option.
In later versions of Bamboo, the option will be called 'Read-Only External User Management'.
Refer to the Bamboo documentation for full details of Bamboo's external management configuration.

2.4 (Optional) Enable Single Sign-On

SSO is optional

Single sign-on (SSO) is optional when integrating Bamboo and other Atlassian products. To use centralised authentication without SSO, skip the steps below.

To configure Seraph-based authentication:

Edit the \bamboo\webapp\WEB-INF\classes\seraph-config.xml and change the authenticator node to read:
```
<authenticator class="com.atlassian.crowd.integration.seraph.BambooAuthenticator"/>
```
Bamboo will also require the latest version of Atlassian Seraph. Copy this JAR file into Bamboo's \bamboo\webapp\WEB-INF\lib directory and remove the old file.

2.5 (Optional) Tune the Cache

When using the atlassian-user and Crowd framework together with Bamboo, it is highly recommended that caching be enabled. 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 in the Crowd application is enabled by default.)

Bamboo 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 in Crowd to users, groups and roles, these changes will not be visible in Bamboo until the cache expires for that specific item (i.e. for the particular user, group or role).

The default value 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).

Crowd の動作を確認する

Welcome to Bamboo with Crowd!

You should now be able to log in using principals belonging to the bamboo-user group. Try adding a principal to the group using Crowd — you should be able to log in to Bamboo using this newly created principal. That's centralised authentication in action!
If you have enabled SSO, you can try adding the Bamboo Directory and bamboo-admin 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 Bamboo administrators to log in to the Crowd Administration Console. Try logging in to Crowd as a Bamboo administrator, and then point your browser at Bamboo. You should be logged in as the same principal in Bamboo. That's single sign-on in action!

Child pages