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"

    (warning) 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:

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

    Alternatively,

    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

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

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

    How do I match 3 attributes?

    Just add an extra clause:

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

    Extra clauses can be added for more than three attributes too.

    Matching Components of Distinguished Names 

    (warning) As Microsoft Active Directory does not implement extensible matching, the following examples won't work with it.

    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.

    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

    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,

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

    becomes

    (&amp;(objectClass=person)(&#33;(objectClass=user)))
    

    Refer to this external documentation on other XML characters that need escaping.

    Sample Filters

    (warning) These filters are written for Active Directory. In order to use them for something such as OpenLDAP the attributes will need to be changed.

    This will only synchronise users in the 'CaptainPlanet' group - this should be applied to the User Object Filter:

    (&(objectCategory=Person)(sAMAccountName=*)(memberOf=cn=CaptainPlanet,ou=users,dc=company,dc=com))

    And this will search for users that are a member of this group, either directly or via nesting:

    (&(objectCategory=Person)(sAMAccountName=*)(memberOf:1.2.840.113556.1.4.1941:=cn=CaptainPlanet,ou=users,dc=company,dc=com))

    28 Comments

    1. So the question is how to you do a NOT

      since in AD LDAP there is user defined as objectClass=top,organizationalPerson,user,person and computer is defined as objectClass=top,organizationalPerson,user,person,computer

      1. Ok, I guess the way around this is to use

        <userSearchFilter>(sAMAccountType=805306368)</userSearchFilter> 

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

    3. To be able to limit your search to users in a collection containing both users and computers, you can also do this:

      (&(objectClass=person)(objectCategory=CN=Person,CN=Schema,CN=Configuration,DC=subdomain,DC=domain))

       ...this is because "computers" usually have the following objectCategory:

      CN=Computer,CN=Schema,CN=Configuration,DC=subdomain,DC=domain

      JXplorer was very helpful in finding these differences.

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

       Example:

    5. Checking for account disablement should really use bitwise checks, because the UAC flag is a bitwise representation.  If one other flag is present, the previous query will fail.

      The correct method is to use the bitwise operator for disabled users (decimal value 2).

      (&(objectclass=user)(objectclass=person)(company=*)(userAccountControl:1.2.840.113556.1.4.803:=2))

      see : UserAccountControl flag usage 

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

      1. See "Matching Components of Distinguished Names" on this page. It matches users in two city groups.

         
        You may be able to search group terms in the USER DNs. This works for our OpenLDAP server.

        For example, to find the group "ou=Newspapers", match the User DN string.

        # roach, Newspapers
        dn: uid=roach,ou=Newspapers,dc=company,dc=com

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

      regards,

      Wim

      1. JExplorer is a Windows-only software. Would you know one running on Linux (preferrably with GTK)?

        1. Apache Directory Studio is free and Java based so runs anywhere: http://directory.apache.org/studio/

    8. Can we have a quick list of the XML attributes

      concat

      symbol

      XML

      AND

      &

      NOT

      !

      OR

      |

      looking for OR

    9. Small typo in the title, it should read "an LDAP filter" instead of "a LDAP filter"...

    10. I need a little help getting my search filter to work, i need to get all users there is at member of a group. The filter i'm trying to use is looking lige this:

      mySearcher.Filter = "(&(objectClass=user)(memberOf=CN=cs-2007))";

      But it dosn't return any values, but if I put in all the groups one member have, it returns the correct answer.

      The group which the users belong to is called cs-2007

      if i use this one it returns the righ:

       mySearcher.Filter = "(&(objectClass=user)(memberOf=CN=cs-2007, cn=users, dc=cliff-test, dc=com))";

      any way i don't have to write all of that??

    11. I am trying to pull groups from two different CNs:

      (&(objectClass=group)(|(CN=ABC*)(CN=DEF-*))) [wildcard search for ABC *OR* DEF- that are groups]

      The results I get back from my ldp.exe query are correct, but Confluence only displays the matches from the first wildcard, ABC*?

      Update: The ABC* results are correct based on the baseGroupNamespace. The other CN is in a different OU. If I change the baseGroupNamespace to one level higher, I get zero results.

    12. 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! 

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

        Example:

    13. I was surprized to discover that this page does not specify that the ou:dn:= is not supported by Microsoft Active Directory. I've spent almost two days trying to find a fix.

      1. 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?

        1. As far as I know, there no way of doing this in Active Directory, you have to code it or you can replace the person or group name with the full CN (in order to have unique names).

          Now I would recommend you to read http://www.selfadsi.org/extended-ad/search-user-accounts.htm which is very valuable resource for Active Directory.

    14. Hi Sir,

      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!

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

      1. Is it possible to do memberOf mutliple groups with confluence-users pattern? 

        (&(objectClass=user)(memberOf=cn=confluence-*,dc=example,dc=com)) I've tried this before and haven't had good results. 

    16. 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)

      My query is as follows:

      (&(objectCategory=user)(|(memberOf=CN=jira-administrators,OU=Atlassian JIRA,DC=ABC,DC=XYZ)(memberOf=CN=jira-reminder,OU=Atlassian JIRA,DC=ABC,DC=XYZ)(memberOf=CN=jira-system-administrators,OU=Atlassian JIRA,DC=ABC,DC=XYZ)(memberOf=CN=jira-users-internal,OU=Atlassian JIRA,DC=ABC,DC=XYZ)))

      Everything I have tried to reduce the length of this, is causing the query not to work, including dropping the OU and DC, and adding wildcards.

    17. If I added a search filter that was too broad and then correct it the users that should be filtered out still appear in the people directory, how do I get them out?

    18. Brett - that happened in my initial setup. I tweaked my filter until it was correct, and then started again with a fresh database copy.

    19. this is an old queue but I still want to find out how to set up query filter to query users only in  two memberOf groups