How to Retrieve LDAP Users and Groups from Various Organizational Units in Confluence
Platform Notice: Data Center - This article applies to Atlassian products on the Data Center platform.
Note that this knowledge base article was created for the Data Center version of the product. Data Center knowledge base articles for non-Data Center-specific features may also work for Server versions of the product, however they have not been tested. Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.
*Except Fisheye and Crucible
Purpose
This article aims to guide instance administrators on how to efficiently fetch users and groups from different Organizational Units (OUs) within an LDAP hierarchy for synchronization with the Confluence application. Directly querying the entire LDAP tree can impose significant overhead on both the LDAP server and the Confluence application. Instead, we will explore strategies to target specific areas of the LDAP structure. This can help administrators sync the necessary users without impacting system performance, ensuring a more focused and efficient LDAP query process.
Environment
Any Confluence instance that is linked to an external LDAP server.
Solution
Confluence synchronizes users and groups from LDAP servers using the Lightweight Directory Access Protocol (LDAP). This synchronization process relies on specific configurations within the user directory and employs LDAP filters to determine which objects to retrieve and its capabilities are limited by the LDAP protocol.
To synchronize users and groups, LDAP filters can use various attributes to specify which entities Confluence should fetch. The main approach is to use a common attribute that identifies specific users and groups. This works well when all necessary entities are within a single base distinguished name (baseDN). However, in complex LDAP hierarchies, users and groups may be spread across multiple Organizational Units (OUs), making it challenging to use a single filter or baseDN.
In such cases, a straightforward solution is to configure each OU or domain within the LDAP hierarchy as separate User Directories in Confluence. This simplifies synchronization by allowing you to set schema settings like BaseDN, Additional User DN, and Additional Group DN for each directory. This approach optimizes synchronization efficiency and avoids searching the entire LDAP tree, reducing synchronization time and minimizing potential performance issues on the LDAP server.
Example
Imagine you are managing a Confluence instance for a company with a multi-branch structure. The company has offices in New York, London, and Tokyo, each with its own Organizational Unit (OU) in the Active Directory (AD). The LDAP structure looks like this:
OU=NewYork,DC=company,DC=com
OU=London,DC=company,DC=com
OU=Tokyo,DC=company,DC=comAnd each OU contains its respective users and groups.
Instead of trying to create a complex LDAP filter to synchronize all users and groups across these OUs, which would go through the entire LDAP tree, you can configure each OU as a separate User Directory in Confluence:
- For New York's OU, set the BaseDN to
OU=NewYork,DC=company,DC=com. - For London's OU, set the BaseDN to
OU=London,DC=company,DC=com. - For Tokyo's OU, set the BaseDN to
OU=Tokyo,DC=company,DC=com.
By setting each OU as a separate User Directory, you can easily manage and adjust the synchronization settings specific to each location. This ensures that you are only retrieving users and groups relevant to each office, enhancing synchronization efficiency and reducing the load on the LDAP server.
Alternatively, you can collaborate with your LDAP administration team to review and potentially restructure the LDAP setup. They might adjust the LDAP structure so that all users and groups needing synchronization share a common attribute or reside within a single Organizational Unit (OU) or domain. However, this option may be more complex as it requires changes to the LDAP database structure.
Additional details on Confluence's LDAP connection and configuring LDAP filters can be found in the below articles: