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

This configuration is not supported. Please see USER-105.

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.

[nickf@little-creatures dls]$ ldapsearch -h 'localhost' -p 389 -D 'cn=admin,dc=atlassian,dc=private' -x -w secret -b 'ou=people,dc=atlassian,dc=private' -s sub

# extended LDIF
#
# LDAPv3
# base <ou=people,dc=atlassian,dc=private> with scope sub
# filter: (objectclass=*)
# requesting: ALL
#

# people, atlassian.private
dn: ou=people,dc=atlassian,dc=private
objectClass: top
objectClass: organizationalUnit
ou: people

... etc.

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

baseUserNamespace=cn=employees,cn=acme,cn=org
userSearchAllDepths=true

[nickf@little-creatures dls]$ ldapsearch -h 'localhost' -p 389 -D 'cn=admin,dc=atlassian,dc=private' -x -w secret -b 'ou=people,dc=atlassian,dc=private' -s one

# extended LDIF
#
# LDAPv3
# base <ou=people,dc=atlassian,dc=private> with scope one
# filter: (objectclass=*)
# requesting: ALL
#

# ldapusera, people, atlassian.private
dn: cn=ldapusera,ou=people,dc=atlassian,dc=private
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: ldapusera
sn: ldapuseraSN
givenName: ldapuseraGN
mail: ldapusera@testingarea.org
userPassword:: cGFzc2E=

... etc.

Would lead to the following values for baseUserNamespace and userSearchAllDepths:

baseUserNamespace=cn=employees,cn=acme,cn=org
userSearchAllDepths=false

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

usernameAttribute=cn

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.

[nickf@little-creatures dls]$ ldapsearch -h 'localhost' -p 389 -D 'cn=admin,dc=atlassian,dc=private' -x -w secret -b 'ou=people,dc=atlassian,dc=private'
 -s sub '(objectClass=inetorgperson)'

# extended LDIF
#
# LDAPv3
# base <ou=people,dc=atlassian,dc=private> with scope sub
# filter: (objectClass=inetorgperson)
# requesting: ALL
#

# ldapusera, people, atlassian.private
dn: cn=ldapusera,ou=people,dc=atlassian,dc=private
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: ldapusera
sn: ldapuseraSN
givenName: ldapuseraGN
mail: ldapusera@testingarea.org
userPassword:: cGFzc2E=

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.

firstnameAttribute=givenname
surnameAttribute=sn
emailAttribute=mail

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

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.

[nickf@little-creatures ~]$ ldapsearch -h 'localhost' -p 389 -D 'cn=admin,dc=atlassian,dc=private' -x -w secret -b 'ou=groups,dc=atlassian,dc=private' -s sub
# extended LDIF
#
# LDAPv3
# base <ou=groups,dc=atlassian,dc=private> with scope sub
# filter: (objectclass=*)
# requesting: ALL
#

# groups, atlassian.private
dn: ou=groups,dc=atlassian,dc=private
objectClass: top
objectClass: organizationalUnit
ou: groups

# groupA, groups, atlassian.private
dn: cn=groupA,ou=groups,dc=atlassian,dc=private
objectClass: top
objectClass: groupOfNames
cn: groupA
member: cn=ldapusera,ou=people,dc=atlassian,dc=private
member: cn=ldapuserb,ou=people,dc=atlassian,dc=private

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

baseGroupNamespace=ou=groups,dc=atlassian,dc=private
groupSearchAllDepths=false
groupnameAttribute=cn

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

[nickf@little-creatures user_standalone]$  ldapsearch -D 'uid=admin,ou=system' -h localhost -p 10389 -x -w secret -s one -b 'ou=groups,ou=system'
'(objectclass=group)'
# extended LDIF
#
# LDAPv3
# base <ou=groups,ou=system> with scope one
# filter: (objectclass=group)
# requesting: ALL
#

# groupA, groups, system
dn: uid=groupA,ou=groups,ou=system
ou: Teams
ou: Human Resources
cn: groupA
objectclass: group
objectclass: top
uid: groupA
l: groupA

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

baseGroupNamespace=ou=groups
groupnameAttribute=uid
groupSearchAllDepths=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'.

# groupA, groups, atlassian.private
dn: cn=groupA,ou=groups,dc=atlassian,dc=private
objectClass: top
objectClass: groupOfNames
cn: groupA
member: cn=ldapusera,ou=people,dc=atlassian,dc=private
member: cn=ldapuserb,ou=people,dc=atlassian,dc=private

membershipAttribute=member

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

[nickf@little-creatures ~]$ ldapsearch -h 'localhost' -p 10389 -D 'uid=admin,ou=system' -x -w secret -b 'ou=users,ou=system' -s sub
# extended LDIF
#
# LDAPv3
# base <ou=users,ou=system> with scope sub
# filter: (objectclass=*)
# requesting: ALL
#

# users, system
dn: ou=users,ou=system
ou: users
objectClass: organizationalUnit
objectClass: top

# ldapusera, users, system
dn: uid=ldapusera,ou=users,ou=system
sn: Surname1
ou: People
ou: Human Resources
cn: ldapusera
objectclass: atlassianPerson
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
uid: ldapusera
userpassword:: cGFzc2E=
givenname: ldapusera
mail: ldapusera@testingarea.org
member: cn=groupA,ou=groups,ou=system
l: Atlassian test subject

... etc.

membershipAttribute=atlassianGroupMemberOf