Integrating Bamboo with LDAP

Before you begin

You will need to confirm that your LDAP server is compatible and set up correctly before integrating it with Bamboo. Please check your LDAP server against the requirements below:

• Check your LDAP server version — Supported versions are v2 and v3. Supported LDAP servers include OpenLDAP, Microsoft Active Directory, Novell eDirectory, and any server that uses Java JNDI-LDAP mapping.
• Check whether your LDAP or Active Directory server supports static groups — Your LDAP or Active Directory server must support static groups. This means that the user DNs must be stored against a membership attribute inside an LDAP group. An example of a static group is shown below:

   Dn: CN=Sales and Marketing,CN=Users,DC=ad,DC=atlassian,DC=com
  objectClass: top; group;
  cn: Sales and Marketing;
  distinguishedName: CN=Sales and Marketing,CN=Users,DC=ad,DC=atlassian,DC=com;
  name: Sales and Marketing;
  ...
  member: CN=John Smith,CN=Users,DC=ad,DC=atlassian,DC=com
  member: CN=Sally Smith,CN=Users,DC=ad,DC=atlassian,DC=com
  ...
  

  
  The membership attribute in this case is member, but this is not required. Note that the full DNs of John Smith and Sally Smith are listed. If the values against member are not full DNs, but are just usernames, then you need to add the flag <useUnqualifiedUsernameForMembershipComparison>true</useUnqualifiedUsernameForMembershipComparison> to your LDAP configuration. Open Directory on OS X uses this configuration.
  
• Ensure that you do not have an LDAP group called 'bamboo-admin'. — The bamboo-admin group is reserved by Bamboo.
• Ensure that you do not have duplicate users on your LDAP — If you have users on your LDAP that are also on Bamboo, the LDAP users will take precedence over your local Bamboo users.
• Ensure that you do not have duplicate groups on your LDAP — If you have groups on your LDAP that are also on Bamboo, this may cause unpredictable behaviour when you attempt to integrate your LDAP server with Bamboo.

Step 1 — Backup your data

We strongly recommend that you backup your data before attempting LDAP integration.

Step 2 — Configure Connection Details

The LDAP server connection is specified by manually editing the file atlassian-user.xml.

To configure your connection details,

Step 3 — Map LDAP Data Tree

To map the LDAP Data Tree,

Filters: <userSearchFilter> and <groupSearchFilter> may use the AD specific filter syntax. Operators such as & need to be escaped.

<userSearchFilter>(&amp;(objectClass=inetorgperson)(memberOf=cn=bamboo-usr,ou=groups,DC=atlassian,dc=com))</userSearchFilter>

Step 4 — Optional LDAP Settings

The following settings do not appear in the default atlassian-user.xml file. Their default values are as follows:

<poolingOn>true</poolingOn>
<maxSize>0</maxSize>
<initSize>10</initSize>
<prefSize>10</prefSize>
<debugLevel>none</debugLevel>
<securityProtocol>plain ssl</securityProtocol>
<authentication>simple</authentication>
<timeout>0</timeout>
<initialContextFactory>com.sun.jndi.ldap.LdapCtxFactory</initialContextFactory>
<batchSize>100</batchSize>
<timeToLive>0</timeToLive>
<userSearchAllDepths>true</userSearchAllDepths>
<groupSearchAllDepths>true</groupSearchAllDepths>

If you want to override these default values, you can specify any or all of them by adding them onto the end of the atlassian-user.xml file. For example, to add your own value for the <initSize> setting, you would add an extra line before the </ldap> line shown in 'Stage 3' above:

...
    <groupnameAttribute>cn</groupnameAttribute>
    <groupSearchFilter>(objectClass=groupOfNames)</groupSearchFilter>
    <membershipAttribute>member</membershipAttribute>
    <initSize>20</initSize>
</ldap>

It is important that the connection pool timeout value be set to 0, as this will force Atlassian User (via the JNDI layer) to clean up lingering connections that have lived past one request. For more information about LDAP pools please see http://java.sun.com/products/jndi/tutorial/ldap/connect/config.html.

You cannot manage LDAP accounts or user groups from Bamboo. Bamboo will continue to use local users and groups, even when LDAP is enabled. If you need to assign LDAP users to particular groups referenced by Bamboo (e.g. for permissions or notifications), the workaround is to assign your LDAP users to local Bamboo groups, and reference these groups rather than LDAP groups.

Please note that once LDAP has been enabled, reverting back to local user management is not possible.

Step 1 — Configuring Bamboo for External User Management

Please ensure that 'Read-only External User Management' is turned OFF in Bamboo before assigning LDAP users to Bamboo groups. The Read-only External User Management check-box in Bamboo controls whether users and groups in Bamboo are editable. Setting this option to OFF will make users and groups in Bamboo read-only (i.e. the implication being that you will be managing your users and groups externally).

If you are using Crowd together with an LDAP, please read the documentation on Integrating Bamboo with Crowd to see our recommended settings for the 'Read-only External User Management' check-box.

To disable Read-only External User Management,

Step 2 — Assigning LDAP Users to Bamboo Groups

Once Bamboo is started with 'Read-Only External User Management' disabled, you can assign LDAP users to Bamboo groups. Please see Adding Users to and removing them from Groups.
Please note, the 'View Users' and 'View Groups' screens in Bamboo currently will not list all of your LDAP users/groups (please see BAM-1963 for details).

To check whether the atlassian-user.xml file is correctly configured, please run the Paddle tool to debug the LDAP configuration in your atlassian-user.xml file. For further reference, please visit the Paddle usage page.