5.13.2 Integrating Bamboo with LDAP

Bamboo supports LDAP integration for authentication and authorisation of LDAP users. However, please note that it is not possible to manage/administer 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.

Also please note that:

• Once LDAP has been enabled, reverting back to local user management is not possible.
• In Bamboo versions prior to 1.2.2 it was not possible to perform XML backups of your Bamboo instance when integrated with LDAP. In Bamboo version 1.2.2, exports are possible, but user data will not be included in the export.
• Bamboo does not currently support multiple LDAP servers. If you need to connect to multiple LDAP servers, please consider using Crowd.
  

Before you begin

Confirm this information about your LDAP server:

1. Check your server LDAP 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.
   
   
2. 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.
   

3. You must not have an LDAP group called 'bamboo-admin'.
4. Make sure you don't have duplicate users on LDAP. In such cases, the LDAP users will take precedence over your local Bamboo users.
5. Make sure you don't have duplicate groups on LDAP as this may cause unpredictable behaviour.

Stage 1 - Backup your data

Please backup your data before attempting LDAP integration.

Stage 2 - Configure Connection Details

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

1. Edit the file .../webapp/WEB-INF/classes/atlassian-user.xml and configure the connection AD or LDAP.
2. Check your configuration against the example connection details shown below.

   <ldap key="ldapRepository" name="LDAP Repository@hecate.atlassian.com" cache="true">
       <host>hecate.atlassian.com</host>
       <port>389</port>
       <securityPrincipal>cn=admin,dc=atlassian,dc=private</securityPrincipal>
       <securityCredential>secret</securityCredential>
       <securityProtocol>plain</securityProtocol>
       <securityAuthentication>simple</securityAuthentication>
       <baseContext>dc=atlassian,dc=private</baseContext>
   
   ....

3. Please ensure that the following line is also active in your atlassian-user.xml (it should be there by default):

   <hibernate name="Hibernate Repository" key="hibernateRepository"  description="Hibernate Repository" />

Stage 3 - Map LDAP Data Tree

1. To configure the mappings in atlassian-user.xml for either AD or LDAP, please see:
   • Mapping Active Directory
   • Mapping other LDAP servers
     
     
2. Check your configuration against the example connection details shown below.

   ...
   
       <baseUserNamespace>dc=staff,dc=perftest,dc=atlassian,dc=private</baseUserNamespace>
       <baseGroupNamespace>dc=groups,dc=perftest,dc=atlassian,dc=private</baseGroupNamespace>
       <usernameAttribute>cn</usernameAttribute>
       <userSearchFilter>(objectClass=inetorgperson)</userSearchFilter>
       <firstnameAttribute>givenname</firstnameAttribute>
       <surnameAttribute>sn</surnameAttribute>
       <emailAttribute>mail</emailAttribute>
       <groupnameAttribute>cn</groupnameAttribute>
       <groupSearchFilter>(objectClass=groupOfNames)</groupSearchFilter>
       <membershipAttribute>member</membershipAttribute>
   </ldap>

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

Stage 5 - External user management

If you do not have rights to update user attributes on your LDAP directory server, you cannot assign LDAP users to Bamboo Groups.

If you do have write access to users on your LDAP directory server, ensure that 'External User Management' is turned OFF in Bamboo before assigning LDAP users to Bamboo groups. You can view the appropriate configuration of this field for all scenarios on this page.

To disable External User Management,

1. Click the 'Administration' link in the top navigation bar.
2. Click the 'Security Settings' link in the left navigation column.
3. De-select the 'Enable External User Management?' check-box.
4. Click the 'Save' button.
   

Stage 6 - Assigning LDAP Users to Bamboo Groups

Once Bamboo is started with LDAP enabled, you can assign LDAP users to Bamboo groups. Please see 5.06 Adding Users to and removing them from Groups.

Troubleshooting

To check whether 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._

RELATED TOPICS

• 5.01 Creating a User
• 5.02 Changing a User's Password or Details
• 5.03 Deleting or deactivating a User
• 5.04 Creating a Group
• 5.05 Deleting a Group
• 5.06 Adding Users to and removing them from Groups
• 5.07 Granting Plan Permissions to Users or Groups
  • 5.07.01 'Bulk Editing' Plan Permissions
• 5.08 Granting Global Permissions to Users or Groups
• 5.09 Granting Administration Rights to a User
• 5.10 Allowing Anonymous Users to access Bamboo
• 5.11 Enabling or disabling Contact Details Display
• 5.12 Enabling or disabling Public Signup
• 5.13 Working with External User Repositories
  • 5.13.1 Integrating Bamboo with Crowd
  • 5.13.2 Integrating Bamboo with LDAP
    • 5.13.2.1 Configuring the Caching of your LDAP Repository