How to Perform LDAP Queries in PowerShell

To query Active Directory, use the Filter parameter with PowerShell expression syntax when that is the syntax supported by the cmdlet. Use -LDAPFilter when you want to write an LDAP search filter. Both approaches require the Active Directory module and an authenticated connection to a domain controller. The sections below cover setup, a user lookup, and LDAP group-filter patterns.

Installing the Active Directory Module in PowerShell

Before querying, install the Active Directory module, use a computer joined to the domain, and authenticate to a domain controller. The module is provided by Remote Server Administration Tools (RSAT); Install-Module alone does not install it.

On supported Windows client editions, the RSAT capability can be added with Add-WindowsCapability -Name Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0 -Online. On Windows Server editions that provide the feature, use Install-WindowsFeature -Name RSAT-AD-PowerShell -IncludeAllSubFeature. These commands are platform- and version-dependent; check that the capability or feature applies to the target operating system and run the command in an appropriately elevated PowerShell session. Installing the RSAT component provides the Active Directory module for Windows PowerShell.

Using the Filter Parameter for Active Directory Queries

The Active Directory module’s Filter parameter accepts PowerShell expression syntax. Compare supported directory properties with operators such as -eq, and quote string values. The * wildcard matches text in a string value. For example, a user lookup by name can be written as Get-ADUser -Filter "Name -eq 'John'". Check the specific cmdlet’s documentation or Get-Help output for its supported parameters and filterable properties; parameter support and property names can vary by cmdlet.

This self-contained example constructs a filter string for a department lookup. Replace the sample value when adapting it to a query; the Active Directory query itself requires the module and domain access described above.

$department = 'Engineering'
$filter = "Department -eq '$department'"
Write-Output $filter

Department -eq 'Engineering'

This example was executed and produced the filter string shown above; it constructs a string and does not contact a directory. Keep the PowerShell expression inside the value passed to -Filter.

Using the -LDAPFilter Parameter for LDAP Queries

LDAP is a vendor-neutral protocol for accessing and modifying directory data. It does not itself secure directory data; use the authentication and transport protections configured for your environment. Active Directory implements LDAP, and its search-filter syntax is defined in RFC 4515. Each filter rule is enclosed in parentheses. When a cmdlet supports -LDAPFilter, this parameter accepts LDAP search-filter syntax; check the relevant cmdlet’s supported parameters before choosing it.

The following are filter values for Get-ADGroup -LDAPFilter. They are syntax illustrations, not standalone commands, and their results depend on the directory:

• Match groups whose common name (cn) is Department: Get-ADGroup -LDAPFilter '(cn=Department)'.
• Match groups whose common name is Department and description is Prod: Get-ADGroup -LDAPFilter '(&(cn=Department)(description=Prod))'.
• Match groups whose common name is either Professional Services Department or Share Access: Get-ADGroup -LDAPFilter '(|(cn=Professional Services Department)(cn=Share Access))'.
• Match groups whose description is not Prod, including entries without that attribute: Get-ADGroup -LDAPFilter '(!(description=Prod))'.
• Match groups whose description is Prod while excluding the common name Department: Get-ADGroup -LDAPFilter '(&(description=Prod)(!(cn=Department)))'.
• Match a description containing the path \\fileserver1\share: Get-ADGroup -LDAPFilter '(description=\5c\5cfileserver1\5cshare)'. In an LDAP filter, \5c represents a literal backslash; escape special filter characters in values according to RFC 4515 when building filters from input.