This document outlines how to go about constructing a more sophisticated filter for the userSearchFilter and groupSearchFilter attributes in your AtlassianUser LDAP config file (for Confluence versions prior to 3.5), and in the directory properties in Confluence Admin > User Directories (for Confluence 3.5 and above).

What is a filter

Filters are used to restrict the numbers of users or groups that are permitted to access Confluence. In essence the filter limits what part of the LDAP tree Confluence syncs from.

A filter can and should be written for both user and group membership. This ensures that you are not flooding your Confluence instance with users and groups that do not need access to your content.

When constructing a filter it is best to pick a common attribute of the set of users you want to allow access to Confluence. This is most often the attribute that denotes group membership or an objectClass like "Person"

The attribute used to denote membership in a group is not common to all flavors of LDAP. Examples of this attribute can be "groupMembership" or "Member"

How do I match more than one attribute?

For example, if my users are distinguished by having two objectClass attributes (one equal to 'person' and another to 'user'), this is how I would match for it:

(&(objectClass=person)(objectClass=user))

Notice the ampersand symbol '&' symbol at the start. Translated this means: search for objectClass=person AND object=user.

Alternatively,

(|(objectClass=person)(objectClass=user))

Translated this means: search for objectClass=person OR object=user.

The pipe symbol '|' denotes 'OR'. As this is not a special XML character, it should not need escaping.

Wildcards

(&(objectClass=user)(cn=*Marketing*))

This means: search for all entries that have objectClass=userANDcn that contains the word 'Marketing'.

Wildcards are unable to be used in filters using ! (or NOT) logical operators. See below

Matching Components of Distinguished Names

You may want to match part of a DN, for instance when you need to look for your groups in two subtrees of your server.

(&(objectClass=group)(|(ou:dn:=Chicago)(ou:dn:=Miami)))

will find groups with an OU component of their DN which is either 'Chicago' or 'Miami'.

Using 'not'

To exclude entities which match an expression, use '!'. Note that this must be represented as the entity '!' in your XML file (if you are using Confluence 3.4 or below).

So

(&(objectClass=group)(&(ou:dn:=Chicago)(!(ou:dn:=Wrigleyville))))

will find all Chicago groups except those with a Wrigleyville OU component.

Note the extra parentheses: (!(<expression>))

For Confluence 3.4 and below, once you have constructed your search filter using this document, you must escape the ampersand symbol and the exclamation mark symbol before adding to your XML file. So for example,

To write an AD query to limit the users to a particular group, add the following user search filter:
<userSearchFilter>(&(objectCategory=user)(memberOf=CN=Employees,OU=Security Groups,DC=yourdomain,DC=com))</userSearchFilter>In this particular query, the group is Employees. You will need to change this value to your target group. You will also need to update the DC.

NOT notation:

I wanted to filter based on users and exclude locked AD accounts, to do this required the use of the NOT expression. Just as the 'and' operation requires you to specify the HTML code for ampersand, so does the not operation require you to specify the HTML code for exclamation.

MS Active Directory and LDAP integration has a limitation with it.
It seems the MS implementation of LDAP does not support search filters based on OU. In my case I had a large AD tree and I only wanted to connect to 3 OUs and no matter what I tried I couldn't get the search filter to filter on the basis of OU.

Further reading and playing around with Saved Queries in the AD Management console confirmed it couldn't be done with a single search filter. You need to point the base of your search at the OU which negates the ability to search multiple OUs at the same level of a tree.

i.e (&(objectClass=user)(ou=Chicago) doesn't work.

The upshot of this is you need to follow the "Two connections to the Same Server" in the Configuring Multiple LDAP repositories method to add multiple OUs.

If you need to write complex queries, you might be better of using JExplorer. It allows you to construct queries in a graphical way. Once you have it ok there, you can ask it the textual representation of the filter and put that in your atlassian-user.xml.

At our large institution, our ADS directory contains thousands of large groups (like Exchange Mail) and other across many different domains. I wish to exclude certain large groups from being copied into Confluence since they have no use or control in Confluence. How can I specify a User Directory Filter to negate certain Groups names?

I think a much better solution would be for Atlassian code to add a flag to the groups that are used within Confluence and only sync those. Most of our AD groups are not used by Confluence YET COPIED IN and SYNCED!

As Confluence didn´t has a 'deny' permission for pages and spaces I used the filter option of <userSearchFilter> to exclude users of groups from access to the Wiki (for sure, you must disable anonymous access for space/page). When you provide the full DN of the memberOf attribute then it works fine.The & and ! must be escaped, as described above. Try it out with JEplorer first.

Thank you your comment save me a long search. I was trying the example in "Matching Components of Distinguished Names" since it's exactly what I needed and it doesn't work. Your comment explained me why it doesn't work. It really should be written right beside the example.

Now I need to find out a way to get the same result with Microsoft Active directory. Did you find one?

i am new to ldap filter and i wish to put in confluence ldap setting to control which group can access confluence. Let say i have a group in AD called confluence-user1. how do i put in filter to allow only this group name of member to access confluence? Your help is much appreciated!

Hi there Choomen, this would be done with a User Filter, because you want to select only users that are members of a particular group. It would look something like this (modified for your system of course):

The 'memberOf' attribute does not exist in all types of LDAP - it does exist in AD so you will be able to use it Choomen, but for anyone else who finds this information, be aware that you may not have the attribute. If that's the case, you would have to find another way to group the users.

Alternatively, depending on your license and the number of users you could sync the whole directory and only give the 'confluence-users1' group 'can use' permission to Confluence.

Hope this helps! If you're stuck and need a hand, you can always contact Support.

Can anyone help me reduce this query to less than 255 characters? I have almost exactly the same query working in Confluence, but when I try to set this up in JIRA I am hitting a length constraint in the directory_attribute table. Confluence is limited to 4000, whereas JIRA is 255! Atlassian are aware of this (JRA-28805)