This page last changed on Jul 15, 2008 by psmith.

The LDAP server connection is specified by manually editing the file atlassian-user.xml. Confluence 2.3 onwards supports multiple LDAP servers by repeating the instructions below for each server so that there are multiple repositories defined.

Stage 1 - Configure Connection Details

  1. Edit the file .../confluence/WEB-INF/classes/atlassian-user.xml and configure the connection for either AD or LDAP.
  2. If your Active Directory Server allows anonymous searches, then you do not need to specify a securityPrincipal and securityCredential at all. For an example of how you would configure Confluence to allow anonymous authentication, see Enable Anonymous Authentication in LDAP or Active Directory

  3. To connect to LDAP over SSL, see Connect to LDAP via SSL

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

Stage 2 - Map LDAP Data Tree

  1. Configuring the mappings in atlassian-user.xml for either AD or LDAP.
  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 3 - Directory Search Depth Settings

These are the default settings:

...
<userSearchAllDepths>false</userSearchAllDepths>
<groupSearchAllDepths>false</groupSearchAllDepths>

The above settings configure the search depth on users and groups. If you set either attribute to:

  • false - Confluence will search only for users/groups directly defined in <baseUserNamespace> and <baseGroupNamespace>.
  • true - Confluence will search for users/groups defined in the above namespaces and also in namespaces nested within them. For example, if your users are distributed across multiple namespaces, you should set this option to true.

Setting the value to true may have a high cost in performance for large directories, because Confluence will search the whole tree and not just the immediate namespace.

Stage 4 - Optional LDAP Settings

The following settings are the default values for all the options under <ldap> in the atlassian-user.xml file. Some of them do not appear in the file normally, but can be added if you need to customise them:

XML tag Default value Description
LDAP connection properties    
securityProtocol plain ssl Allow encrypted (SSL) connections. Can be omitted if anonymous access is available.
authentication simple Plain-text password transmission. Can be 'none' if anonymous access to the LDAP server is available.
initialContextFactory com.sun.jndi.ldap.LdapCtxFactory Class name of LDAP provider (default: Sun JNDI)
batchSize 100 Size of pages in search results
poolingOn true Use connection pooling
connectTimeout 30000 Timeout in milliseconds when opening new server connections. Default: 30 seconds.
readTimeout 60000 Timeout in milliseconds for search and other read operations. Default: 60 seconds.
LDAP connection pool properties    
initSize 1 Initial size of connection pool, e.g. number of connections to open at start-up. [1]
prefSize 10 Preferred size of connection pool. [1]
maxSize 0 Maximum size of connection pool. Zero means no maximum size. [1]
timeout 300000 Idle time in milliseconds for a connection before it is removed from the pool. Default: 5 minutes. [1]
debugLevel none Debug level for logging. [1]
poolAuthentication simple Authentication for pool connections. [1]
LDAP search properties    
timeToLive 0 Time limit on searches in milliseconds. Zero means no limit. [2]
userSearchAllDepths false Whether user searches should search through the LDAP tree or only for direct children of the DN specified by the userSearchFilter. [3]
groupSearchAllDepths false Whether group searches should search through the LDAP tree or only for direct children of the DN specified by the groupSearchFilter. [3]
useUnqualifiedUsernameForMembershipComparison false If set to true, Confluence will use the value of the usernameAttribute on the user to check for group membership comparisons instead of the complete distinguished name.

Notes

  1. The connection pool properties provided by Atlassian-User correspond with the connection pooling properties in JNDI. See this documentation for further information.
  2. More information on this time limit is available on Sun's JNDI tutorial.
  3. The "searchAllDepths" parameters toggle between SearchControls.SUBTREE_SCOPE (true) and SearchControls.ONELEVEL_SCOPE (false). See Sun's JNDI tutorial on scope configuration for more information.

To override the default values listed above, you can add the value inside your <ldap> tag after the rest of your configuration:

<ldap ...>
...
    <groupnameAttribute>cn</groupnameAttribute>
    <groupSearchFilter>(objectClass=groupOfNames)</groupSearchFilter>
    <membershipAttribute>member</membershipAttribute>
    <initSize>20</initSize>      <!-- bigger initial connection pool! -->
</ldap>

Stage 5 - Optional: Configure LDAP for User Authentication Only

Explanation

If you'd like to configure LDAP for user management and authentication only, start by configuring LDAP integration with groups, and continue to this point to remove group management. i.e. to have users and groups automatically updated from LDAP, and to use LDAP groups for group permissions.

Applies For

  • Enabling LDAP for the first time
  • Upgrading existing LDAP without enabling group management

Important Points

  • LDAP users will be mapped to Confluence. If the Confluence username coincides with the LDAP username, the password lookup is done against LDAP. Group management will happen in Confluence.
  • Each LDAP user must be added to an internal Confluence group having Can Use permissions in order for those LDAP users to access Confluence. If a password is created for an LDAP user in Confluence, it will be ignored as the LDAP password will override it.

Instructions

If you do not wish Confluence to retrieve any of your LDAP groups and display them inside Confluence then you can do this by specifying a dummy value for the groupSearchFilter filter in your atlassian-user.xml file. That is, update your atlassian-user.xml file with the following:

<groupSearchFilter>(objectClass=dummyValue)</groupSearchFilter>

An example atlassian-user.xml file:

<baseUserNamespace>cn=users,dc=ad,dc=atlassian,dc=com</baseUserNamespace>
<baseGroupNamespace>ou=groups,dc=ad,dc=atlassian,dc=com</baseGroupNamespace>
<usernameAttribute>sAMAccountName</usernameAttribute>
<userSearchFilter>(objectClass=user)</userSearchFilter>
<firstnameAttribute>givenname</firstnameAttribute>
<surnameAttribute>sn</surnameAttribute>
<emailAttribute>mail</emailAttribute>
<groupnameAttribute>cn</groupnameAttribute>
<groupSearchFilter>(objectClass=dummyValue)</groupSearchFilter>
<membershipAttribute>member</membershipAttribute>
<userSearchAllDepths>false</userSearchAllDepths>
<groupSearchAllDepths>false</groupSearchAllDepths>

Please note: You will still have to provide a valid LDAP DN for baseGroupNamespace. Confluence still performs a search for groups quite frequently, so you should use a DN without many child nodes, like an individual user DN.

Optional: Configuring Multiple LDAP Repositories

For some LDAP servers, it might be necessary to configure Confluence to connect to multiple LDAP servers. This functionality is available in Confluence 2.3 and above, and has a separate guide: Configuring multiple LDAP repositories.

RELATED TOPICS

Add LDAP Integration
Configuring multiple LDAP repositories
atlassian-user.xml reference
How to write a LDAP search filter, in the Atlassian Development space.

Document generated by Confluence on Aug 07, 2008 19:05