Page tree
Skip to end of metadata
Go to start of metadata

Bamboo can be integrated with LDAP for the authentication and authorization of LDAP users. The instructions below describe how you can set this up. Please note that Bamboo does not currently support multiple LDAP servers. If you need to connect to multiple LDAP servers, please consider using Atlassian's Crowd.

If you choose to integrate Bamboo with LDAP, please note that you cannot manage LDAP accounts or user groups from Bamboo. Please refer to the instructions on this page for details on how to manage your users and groups.

(warning) In Bamboo version 1.2.2 and later, XML backups of your Bamboo instance do not include LDAP user data.

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

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 behavior 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" cache="true">
    You can use the verifySslCertificateHostname setting to verify that the SSL certificate of the LDAP server has the same host as the LDAP connection settings:
    <ldap key="ldapRepository" name="LDAP" cache="true">

    If the verification fails, the following error is returned in the logs:

    Host verification in the LDAP certificate failed. Check whether the hostname in the LDAP connection settings matches the hostname in the server certificate. To disable the validation, set the verifySslCertificateHostname property to 'false' in atlassian-users.xml.


    Host verification works only for LDAPS connections, so the securityProtocol setting of the LDAP connection must have an ssl value.

  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:
  2. Check your configuration against the example connection details shown below.


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


Making Sure that the LDAP Filters are Precise

Depending on the LDAP server being used, different object types may have common objectClass values. In this case, please customize the User and Group filters so that Bamboo can fetch only the objects that are really useful for the application. If your directory server does not display the literal object LDIF details, you may want to use an LDAP browser tool like Apache Directory Studio to check if the filters are restricting the objects correctly based on one or more object attributes.

Step 5 — Optional LDAP Settings

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

<securityProtocol>plain ssl</securityProtocol>

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:


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

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.

(warning) 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).

(info) 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.
(warning) 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 Crowdlicenses and pricing, or download a 30 day free trial.


For more information about caching, see Configuring the caching of your LDAP repository.


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