This page last changed on Mar 12, 2008 by alui.

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

Please ensure that 'Read-only External User Management' is turned ON in Bamboo before assigning LDAP users to Bamboo groups.


To disable Read-only 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 'Read-only External User Management' check-box.
  4. Click the 'Save' button.

Stage 6 - 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 5.06 Adding Users to and removing them from Groups. Note: the 'View Users' and 'View Groups' screens in Bamboo will currently not list all of your LDAP users/groups (please see BAM-1963 for details).

Troubleshooting

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.

Document generated by Confluence on Apr 14, 2008 01:39