How to write LDAP search filters

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

This document outlines how to go about constructing a more sophisticated filter for the User Object Filter and Group Object Filter attributes in your LDAP configuration for Atlassian applications.

What is a filter

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

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

Solution

When constructing a filter it is best to pick a common attribute of the set of users you want to allow access to the application. 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 objectClass=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=user AND cn that contains the word 'Marketing'.

Wildcards are not supported when used in filters using ! (or NOT) logical operators. See below

The LDAP services themselves do not support wildcards for memberOf attribute and other Distinguished Name when setting up LDAPFilter.

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

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.

(&(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 '!'.

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

Note that if using 'not' (ie. '!' to exclude objects) it must be represented as the entity '!' in your XML file if you are using Confluence 3.4 or below.

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

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

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

Sample Filters

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

For reference:

Friendly reminder:

These filters below should be applied to the User Object Filter in the User Directory settings of your Atlassian application

This will only synchronize users in the 'CaptainPlanet' group

(&(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))

Important for Active Directory to have memberOf:1.2.840.113556.1.4.1941 if you want to find nested groups (do not replace the numeric string) inside CaptainPlanet group.

This will search for users who are a member of any or all the 4 groups (fire, wind, water, heart)

(&(objectCategory=Person)(sAMAccountName=*)(|(memberOf=cn=fire,ou=users,dc=company,dc=com)(memberOf=cn=wind,ou=users,dc=company,dc=com)(memberOf=cn=water,ou=users,dc=company,dc=com)(memberOf=cn=heart,ou=users,dc=company,dc=com)))

This will search for users that have an email address

(&(objectCategory=Person)(sAMAccountName=*)(mail=*))

This will search for users that have an email address and are a member of any or all of the groups in the filter below

(&(objectCategory=Person)(sAMAccountName=*)(mail=*)(|(memberOf=cn=fire,OU=Atlassian Groups,dc=xxxx,dc=com)(memberOf=cn=wind,OU=Atlassian Groups,dc=xxxx,dc=com)(memberOf=cn=water,OU=Atlassian Groups,dc=xxxx,dc=com)(memberOf=cn=heart,OU=Atlassian Groups,dc=xxxx,dc=xxxx)))

This will search and import users from different CNs when added to User Object Filter . As a result users from "Jira Administrators", "jira-users" and "confluence-administrators" will be synced to the Atlassian application.

(&(objectCategory=Person)(sAMAccountName=*)(|(memberOf=CN=Jira Administrators,CN=Users,DC=test,DC=mydomain,DC=com)(memberOf=CN=jira-users,CN=Users,DC=test,DC=mydomain,DC=com)(memberOf=CN=confluence-administrators,CN=Users,DC=test,DC=mydomain,DC=com)))

Products

Jira Software

Jira Service Management

Jira Work Management

Confluence

Bitbucket

Resources

Documentation

Community

System Status

Suggestions and bugs

Marketplace

Billing and licensing

How to write LDAP search filters

User Management Troubleshooting and How-To Guides

On this page

Still need help?

Purpose

What is a filter

Solution

How do I match more than one attribute?

Wildcards

How do I match 3 attributes?

Matching Components of Distinguished Names

Using 'not'

Sample Filters

This will only synchronize users in the 'CaptainPlanet' group

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

This will search for users who are a member of any or all the 4 groups (fire, wind, water, heart)

This will search for users that have an email address

This will search for users that have an email address and are a member of any or all of the groups in the filter below

This will search and import users from different CNs when added to User Object Filter . As a result users from "Jira Administrators", "jira-users" and "confluence-administrators" will be synced to the Atlassian application.

RELATED TOPICS

Description	This document outlines how to go about constructing a more sophisticated filter for the User Object Filter and Group Object Filter attributes in your LDAP configuration for Atlassian applications.
Product	Jira, Confluence, Bamboo, Bitbucket
Platform	Server

Page

Viewport

Confluence

How to write LDAP search filters

User Management Troubleshooting and How-To Guides

On this page

Related content

Still need help?

Purpose

What is a filter

Solution

How do I match more than one attribute?

Wildcards

How do I match 3 attributes?

Matching Components of Distinguished Names

Using 'not'

Sample Filters

This will only synchronize users in the 'CaptainPlanet' group

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

This will search for users who are a member of any or all the 4 groups (fire, wind, water, heart)

This will search for users that have an email address

This will search for users that have an email address and are a member of any or all of the groups in the filter below

This will search and import users from different CNs when added to User Object Filter . As a result users from "Jira Administrators", "jira-users" and "confluence-administrators" will be synced to the Atlassian application.

RELATED TOPICS

Related content