Integrating Bamboo with LDAP

Integrating Bamboo with LDAP

Step 1 — Prerequisites

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 in your LDAP directory — If you have users in your LDAP directory that are also on Bamboo, the first repository definition in your atlassian-user.xml file will take precedence.
• Ensure that you do not have duplicate groups in your LDAP directory — If you have groups in your LDAP directory that are also on Bamboo, this may cause unpredictable behaviour when you attempt to integrate your LDAP server with Bamboo.

Step 2 — Backup your data

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

Step 3 — Configure Connection Details

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

To configure your connection details:*

1. Edit the file .../{BAMBOO-HOME}/xml-data/configuration/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" />
   

Step 4 — Map LDAP Data Tree

To map the 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>
   

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 5 — 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 to 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.

External User Management

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.

1. Click the  icon in the Bamboo header and choose Overview.
2. Select User Repositories (under 'Security').
3. Choose Custom user repository.
4. Click Save.

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 ON 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:

1. Click the  icon in the Bamboo header and choose Overview.
2. Select Security Settings (under 'Security') in the left navigation panel.
3. Clear the Read-only External User Management check-box.
4. Click Save.

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 Changing members of 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).

Delegated LDAP

Bamboo does not currently support native delegated LDAP functionality, however an LDAP functionality compromise exists if you are an Atlassian Crowd customer:

1. Configure Crowd to use a Delegated Authentication Directory
2. Configure Crowd for Integration with Bamboo using Crowd as the directory for Bamboo.

Note that when using this approach, users will still be required to log in to Crowd at least once before Bamboo is able to read or authenticate from Crowd.

Find out more about Atlassian Crowd, licenses and pricing, or download a 30 day free trial.

Notes

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