This page last changed on Jun 02, 2008 by smaddox.

This page describes the function of each of the tags in an atlassian-user.xml file. These can be added as child tags of the <ldap> tag in your atlassian-user.xml file to configure each option.

Developer note: this information is derived from atlassian-user-defaults.xml, which can be found in the source of Atlassian-User under src/main/resources/. It also ships in atlassian-user.jar.

Core settings

These settings do not have a default value and must be provided to configure an LDAP connection.

XML tag Description
LDAP connection properties  
host The host name of the machine running the LDAP server. This must resolve from the machine running Confluence.
port The port number that the LDAP server is running on. This should usually be 389.
securityPrincipal The distinguished name (DN) of a user who is allowed to browse the entire LDAP repository. This can be omitted if the repository has anonymous access enabled.
securityCredential The password for the user configured as the securityPrincipal. This can be omitted if the repository has anonymous access enabled. [1]
baseContext The DN of the top of the LDAP tree that contains both users and groups.
LDAP user mapping properties  
baseUserNamespace The DN at the top of the LDAP tree which contains users. For example: ou=users,dc=example,dc=com.
userSearchFilter An LDAP search filter which matches only users under the baseUserNamespace. For example: (objectClass=person). [1]
usernameAttribute The attribute on a user in LDAP which contains the Confluence username. It must be unique across all users. For example: cn (OpenLDAP), sAMAccountName (AD).
firstnameAttribute The attribute on a user in LDAP which contains the first name of the user. For example: givenName.
surnameAttribute The attribute on a user in LDAP which contains the last name of the user. For example: sn.
emailAttribute The attribute on a user in LDAP which contains the email address of the user. For example: mail.
LDAP group mapping properties  
baseGroupNamespace The DN at the top of the LDAP tree which contains groups. For example: ou=groups,dc=example,dc=com.
groupSearchFilter An LDAP search filter which matches only group entities under the baseGroupNamespace. For example: (objectClass=group). [1]
groupnameAttribute The attribute on a group in LDAP which contains the Confluence group name. It must be unique across all groups. For example: cn.
membershipAttribute The attribute on a group in LDAP which contains the DN of each member in the group. [2] For example: member.

Notes

  1. If these values contain ampersands, they must be escaped in the XML file. This is a common situation with LDAP search filters and passwords containing ampersands. For example, the LDAP search filter (&(objectClass=user)(mail=*@example.com)) would be put in the XML as: <userSearchFilter>(&amp;(objectClass=user)(mail=*@example.com))</userSearchFilter>.
  2. This can also contain the user name of each member of the group. See the useUnqualifiedUsernameForMembershipComparison optional configuration setting below.

Optional settings

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.
RELATED TOPICS

Customising atlassian-user.xml
Add LDAP Integration
LDAP User Management

Document generated by Confluence on Dec 03, 2008 15:04