How to map LDAP Users and Groups to Confluence via Atlassian User

This documentation is out of date Please refer to the latest documentation on Understanding User Management in Confluence and Connecting to an LDAP Directory.

Instructions here relate to use of the command line 'ldapsearch' utility to check that mappings between Atlassian User and your LDAP system are correct.

Mappings between LDAP and Atlassian User.

Here is an explanation of each property in the atlassian-user.xml file.

Also read below to learn how to specify a group adaptor, LDAP user and group factories, and a LDAP user searcher.

Converting Special Characters

There are 5 special characters that you must escape when saving search filters to the atlassian-user.xml file.

User Mappings

1. Identifying the baseUserNamespace and the userSearchAllDepths mappings

The baseUserNamespace indicates the top level of a tree in your LDAP system which holds your users. The userSearchAllDepths property can either be set to true or false. True indicates that only the level directly beneath the baseUserNamespace should be searched, false indicates that all additional sub-levels of the tree should be searched.

For example, if you wanted to include users beneath 'cn=contractors,cn=employees,cn=acme,cn=org' and users beneath 'cn=permanent,cn=employees,cn=acme,cn=org' in an Atlassian application you would specify a baseUserNamespace of 'cn=employees,cn=acme,cn=org' with a userSearchAllDepths value of 'true'. Otherwise, if all users are grouped in one level of your tree, set userSearchAllDepths to false.

Would lead to the following values for baseUserNamespace , userSearchAllDepths, and usernameAttribute:

Would lead to the following values for baseUserNamespace and userSearchAllDepths:

Here, also, the usernameAttribute property is identified as being 'cn'. The property mapping therefore becomes

2. Identifying the userSearchFilter

The userSearchFilter allows for an extra condition to be placed on search results. This is useful if a search on the baseUserNamespace is returning results which will not equate to User objects. Use it to specify a search criteria which will identify users.

Here, we specify userSearchFilter as '(objectClass=inetorgperson)'. That is, we are saying our users are identified by an objectClass of inetorgperson (given our search result above, we could have also used organizationalPerson or person). Please note that inetorgperson is an LDAP objectClass. It does not exist in Active Directory. You will need to specify a different class if using AD.

3. Identifying the firstnameAttribute, surnameAttribute, and emailAttribute

As with the identification of username property search above, similar mappings can be found for firstnameAttribute, surnameAttribute, and emailAttribute.

Group Related Mappings

4. Identifying the groupnameAttribute and the baseGroupNamespace mappings

The tactic here is similar identifying the baseUserNamespace and userSearchAllDepths attributes.

It is assumed that groups are entries in their own right within your LDAP system. If groups exist by virtue of being listed against user entries, or in some other way, please raise a support request to discuss an integration plan.

The baseGroupNamespace indicates the top level of a tree in your LDAP system which holds groups. As with userSearchAllDepths, setting groupSearchAllDepths to true instructs the search function to traverse all available subtrees beneath the baseGroupNamespace. Set it to false if all of your groups are contained in the level indicated by baseGroupNamespace.

Static vs Dynamic Groups

Dynamic group configuration is not supported as it is not currently tested. Please see USER-105 for related discussions.

Groups are generally one of two types in LDAP systems - static or dynamic. A static group maintains its own membership list. A dynamic group records its membership on a user entry.

Here is an example of a search on an OpenLDAP DIT (Data Information Tree), which stores static groups.

The baseGroupNamespace is identified as being 'ou=groups,dc=atlassian,dc=private', the groupSearchAllDepths is 'false', and the groupnameAttribute as being 'cn':

Here is an example of a search on an Apache Directory Server DIT (Data Information Tree), which stores dynamic groups.

Here the baseGroupNamespace is 'ou=groups', groupNameAttribute is 'cn', and groupSearchFilter is false.

You will notice that for the baseGroupNamespace I drop the full path: <ou=groups,ou=system> . This is just for convenience with ApacheDS. Whereas OpenLDAP requires the baseGroupNamespace mapping to be the full DN of the node, ApacheDS uses the baseContext property specified in connection.properties to complete it.

5. Identifying the groupSearchFilter filter.

As with the userSearchFilter property, the groupSearchFilter allows you to specify an added search criteria to all search results. This is useful if your baseGroupNamespace holds data which cannot be modelled into a Group alongside data which can be.

Please see the discussion on userSearchFilter for an example of how to build this property.

The default value for this filter is (objectClass=groupOfNames). If you are using Active Directory, please change it to (objectClass=group) or select another objectClass that exists in your instance

Membership Mappings

6. Identifying a membership attribute

There are two requirements for membership mappings to work.

1. The membership value must carry the DN of the user or group, for static and dynamic groups respectively.
2. The search for membership is constructed by using the username or groupname, for static or dynamic groups, attribute and attribute value, along with the the baseContext. If these values do not match membership will not work.

The membershipAttribute property can be identified via the same search which identified the baseGroupNamespace . On a static group, an attribute will be present to identify a membership list.

For example, in the search result below, the membershipAttribute is 'member'.

Whereas, in the example for dynamic above, the membershipAttribute is not on the group but, instead, on the user: