LDAP query syntax: Filters, examples, and PowerShell commands

An LDAP query can be defined as a request sent to a directory service that enables the service to search for information or filter information based on specific criteria. LDAP queries can be regarded as the major means of communication that can be used to connect to directory services such as Microsoft Active Directory, OpenLDAP, and other X.500 directories.

What is an LDAP query?

LDAP, which stands for Lightweight Directory Access Protocol, is used for accessing directory information over a network. A directory service is a database that stores information about users, computers, and resources in an organized, hierarchical tree structure.

An LDAP query is an operation that enables an application or an administrator to query the directory tree for information that meets specific criteria. The result is a list of directory objects and their associated attributes.

Typical LDAP query uses include accessing user information such as contact information, validating group information, accessing computer information, accessing account information based on specific status flags, and using directory information for identity management.

Key concepts in LDAP queries

Base DN: The Distinguished Name (DN) that specifies the search root. The directory tree is searched downward from this point. Example: DC=example, DC=com.

Search scope: Specifies the search extent from the base DN. Base searches only the base DN entry itself. One searches one level directly below it. Sub searches the base DN and all entries anywhere beneath it.

LDAP filter: An expression enclosed in parentheses that specifies which entries are to be returned. Filters match attribute values against search criteria.

Attributes: The fields to return for each matching object, such as cn (common name), mail (email address), or sAMAccountName (logon name).

Size limit: The maximum number of entries the server will return. Active Directory defaults to 1,000 entries per query. Paged searches are required to retrieve larger result sets.

LDAP query syntax

A full LDAP search request is made up of four elements: the base DN, the search scope, the filter, and the list of attributes to retrieve. The LDAP filter is the most complicated of these four elements and determines which directory entries will be returned.

Basic LDAP filter syntax

An LDAP filter is a string enclosed in parentheses. The basic format for a single condition is:

Common operators used in LDAP filter syntax:

Compound LDAP filters

Multiple filter conditions can be combined using logical operators. The operator is placed before the grouped conditions:

The compound filter structure wraps the operator and all its conditions together:

LDAP search filter examples

The most common operation in Active Directory management is group membership queries. There are several LDAP filter patterns, depending on whether you need to retrieve information about user or group membership.

• All user objects:
Click to copy script
(objectClass=user)
• User by login name (sAMAccountName):
Click to copy script
(&(objectClass=user)(sAMAccountName=jdoe))
• User by display name:
Click to copy script
(&(objectClass=user)(displayName=Jane Doe))
• All enabled user accounts:
Click to copy script
(&(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))
• All disabled user accounts:
Click to copy script
(&(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=2))
• Users with a specific email domain:
Click to copy script
(&(objectClass=user)(mail=*@example.com))
• Users whose password never expires:
Click to copy script
(&(objectClass=user)(userAccountControl:1.2.840.113556.1.4.803:=65536))
• Users in a specific department:
Click to copy script
(&(objectClass=user)(department=Engineering))
• All computer objects:
Click to copy script
(objectClass=computer)
• All security groups:
Click to copy script
(&(objectClass=group)(groupType:1.2.840.113556.1.4.803:=2147483648))
• Objects with a partial name match:
Click to copy script
(cn=John*)
• Users created after a specific date:
Click to copy script
(&(objectClass=user)(whenCreated>=20240101000000.0Z))

LDAP query for group membership

Group membership queries are among the most frequent tasks in Active Directory administration. There are several LDAP filter patterns depending on whether you need to find a user's groups or a group's members.

Find all groups a user is a member of

Query the user object and retrieve its memberOf attribute. Each value returned is the DN of a group the user belongs to:

Return the memberOf attribute for the matching entry. The result lists the DN of each group.

Find all direct members of a group

To return all user objects that are direct members of a specific group, filter on the memberOf attribute of user objects:

Find nested group membership

Active Directory supports nested groups. To find all users in a group including those added through nested groups, use:

Find all groups in a specific OU

Set the base DN to the target OU and filter for group objects:

With base DN: OU=Groups,DC=example,DC=com and scope set to Sub.

LDAP query in PowerShell

There are two ways to use LDAP queries in PowerShell: the built-in .NET class DirectorySearcher, which does not require additional modules, and the Active Directory module's cmdlets, which use a higher level abstraction.

Using DirectorySearcher (.NET)

The DirectorySearcher class is available in any Windows environment without the need to install additional modules:

Setting PageSize enables paged searches, which allows retrieval of more than 1,000 results from Active Directory.

Using Get-ADUser with an LDAP filter

The Active Directory module's Get-ADUser cmdlet accepts LDAP filters via the -LDAPFilter parameter. Paging is handled automatically:

Using Get-ADObject for other object types

For computers, groups, or any other object class, use Get-ADObject:

LDAP query for group membership in PowerShell

To find all members of a group including nested members:

LDAP query tool options

There are a number of tools that can be used to create, test, and execute LDAP queries. The choice of which tool to use will depend on the operating system that you are using, as well as whether you want a graphical interface or command line access.

Using LDP.exe

LDP.exe is a Windows Server native utility for manually executing and debugging LDAP queries against Active Directory:

1. Run LDP.exe from the Run dialog box or command prompt.
2. Click Connection > Connect and type the domain controller name and port number (389 for LDAP and 636 for LDAPS).
3. Click Connection > Bind to log on using a domain account.
4. Click Browse > Search to specify the base DN, scope, and filter and execute the LDAP search query.

Using ldapsearch on Linux and macOS

ldapsearch is the standard command-line LDAP query tool on Linux and macOS:

The -H flag is used to specify the LDAP server URI, -D is the bind DN for authentication, -W is used to prompt for the password, -b is used to set the search base DN, -s is used to set the scope (base, one, or sub), the filter follows in quotes, and the remaining arguments are the attributes to retrieve.

LDAP query best practices

Use the most specific base DN available. Using the root of the directory as the base DN causes the server to search the entire directory. Limiting the search to the target OU greatly reduces the load and query time.

Include objectClass in all filters. Using filters such as objectClass=user or objectClass=computer prevents accidental matches on contacts, service accounts, or other objects that may have the same attributes.

Use a minimal attribute list. Using a minimal attribute list cuts network traffic and response sizes. Using the * wildcard to request all attributes should be limited to troubleshooting queries.

Filter on indexed attributes. Attributes such as sAMAccountName, cn, mail, and objectClass are indexed by default in Active Directory. Filtering on unindexed attributes causes the server to perform a full directory scan, which can impact domain controller performance.

Avoid leading wildcards. Filters such as (cn=Smith) cannot utilize the attribute index and require a sequential scan. Use trailing wildcards (cn=Smith) whenever possible.

Enable paged searches for large result sets. Active Directory has a default limit of 1,000 entries per search. A PageSize value should be provided to the DirectorySearcher object, or use Get-ADUser or Get-ADObject, which will handle paging internally.

Test filters before use in production. Validate LDAP filters using LDP.exe or ldapsearch before using them in scripts or applications.

The limitations of native LDAP query tools

While using native tools such as LDP.exe, ldapsearch, or PowerShell scripts to execute LDAP queries is fine for ad-hoc queries and troubleshooting, as your Active Directory environment scales, the shortcomings of such an approach become clear.

Using native LDAP query tools means that you need to know the filter syntax, attribute names, and the DN path before you can even hope to get any meaningful results. There is no query library, no scheduling, no delegation, and no audit trail of who queried what and when. Reports have to be manually collated from raw data. And when a junior admin or help desk personnel wants directory information, giving them direct LDAP access means giving them read access to the directory itself.

ADManager Plus is an Active Directory management and reporting tool that overcomes these shortcomings. Instead of having to build LDAP queries by hand, ADManager Plus provides a point-and-click interface that translates common administrative tasks into directory queries automatically and displays the results in structured, reportable formats.

ADManager Plus delivers:

• Ready-to-use Active Directory reports on users, groups, computers, and organizational units.
• Group membership reports that display direct and indirect membership in the entire directory, exportable to CSV, HTML, XLS or PDF.
• Comprehensive exportable user attribute reports without having to write a single query.
• Scheduled reports that send the results via email on a predetermined schedule.
• Role-based delegation that allows help desk technicians and junior administrators to access particular reports and management operations without showing them the actual directory access.
• Audit and compliance reports with a comprehensive history of who viewed or modified what in Active Directory.

FAQs

What is the difference between an LDAP query and an LDAP filter?

An LDAP query is the complete search request sent to a directory server. It includes the base DN, which stands for Distinguished Name and which is the unique identifier for an entry in the directory tree. The LDAP query also includes s earch scope, filter, and the list of attributes to return. An LDAP filter is specifically the expression within the query that defines which entries should match. The filter is one component of the broader LDAP query.

What is the difference between LDAP and Active Directory?

LDAP is an open protocol standard for accessing directory services. Active Directory is Microsoft's directory service implementation, which uses LDAP as one of its core protocols. Active Directory extends the standard LDAP schema with Microsoft-specific attributes such as userAccountControl, sAMAccountName, and msDS-PrincipalName that are not part of the base LDAP specification.

What port does LDAP use?

Standard LDAP uses port 389. LDAP over SSL (LDAPS) uses port 636. Active Directory also supports port 3268 for Global Catalog queries, which allows searching across all domains in a forest. LDAPS for Global Catalog uses port 3269.

Can an LDAP query search across multiple domains?

A standard LDAP query is scoped to a single domain. To search across all domains in an Active Directory forest, connect to the Global Catalog on port 3268 instead of a standard domain controller on port 389. The Global Catalog contains a partial attribute replica of every object across all domains in the forest.

Why does my LDAP query return no results even though the object exists?

The most common causes are a base DN that does not include the OU containing the object, a scope set to Base or One when Sub is needed, a filter that references an incorrect attribute name, or a bind account that lacks read permission on the target OU or object. Use LDP.exe to test each element of the query interactively to isolate the problem.

What is the default size limit for LDAP queries in Active Directory?

Active Directory returns a maximum of 1,000 entries per query by default. This limit is set by the MaxPageSize policy on the domain controller. To retrieve more than 1,000 results, use paged searches. Get-ADUser and Get-ADObject in PowerShell handle paging automatically. When using the DirectorySearcher class directly, set the PageSize property to a value greater than zero to enable paging.

What does DN mean in an LDAP query?

A Distinguished Name describes the full path from the entry to the root of the directory, expressed as a series of attribute-value pairs separated by commas. For example: CN=Jane Doe,OU=Sales,DC=example,DC=com. Each component of the DN from right to left describes a progressively more specific level of the directory hierarchy.