/flags/active-directory/get-aduser-searchbase-searchscope
Get-ADUser -SearchBase and -SearchScope: search one OU, with or without sub-OUs
- tool
- Active Directory PowerShell
- command
- Get-ADUser
- flag
- -SearchBase <DN>, -SearchScope Base|OneLevel|Subtree
- default
- SearchBase: the default naming context of the domain; SearchScope: Subtree
Get-ADUser -Filter * -SearchBase "OU=Sales,DC=contoso,DC=com" returns only the users inside that OU and its child OUs. Add -SearchScope OneLevel to return only the users directly in the OU, without sub-OUs. Without -SearchBase, Get-ADUser searches the whole domain: outside an AD drive, "the default value of this parameter is the default naming context of the target domain."
Import-Module ActiveDirectory
Get-ADUser -Filter * -SearchBase "OU=Sales,DC=contoso,DC=com"
Get-ADUser -Filter * -SearchBase "OU=Sales,DC=contoso,DC=com" -SearchScope OneLevel
Get-ADUser -Filter 'Enabled -eq $false' -SearchBase "OU=Staff,DC=contoso,DC=com" -Properties LastLogonDate-SearchScope values
From the reference:
| Value | Searches | Note |
|---|---|---|
| Base or 0 | only the object named in -SearchBase | with an OU as base, no user is returned |
| OneLevel or 1 | the immediate children of the base | works only when an OU is given as the base |
| Subtree or 2 | the base and all objects below it | the behaviour you get by default |
Writing the DN
-SearchBase takes a distinguished name, from the most specific part to the domain: OU=Laptops,OU=Computers,OU=Berlin,DC=contoso,DC=com. Rules that trip people up:
- Use
OU=for organizational units andCN=for containers: the built-inUsersandComputersfolders are containers, so the base isCN=Users,DC=contoso,DC=com. - Quote the DN; values with commas inside a name must be escaped with a backslash.
- An empty string as
-SearchBasesearches all partitions only when you are connected to a global catalog port; otherwise "an error is thrown".
Pitfalls
- Wrong DN. A base that does not exist fails with a "directory object not found" style error rather than returning nothing; check it with
Get-ADOrganizationalUnit -Identity "OU=...". - OneLevel on a user. If the base is a user object, OneLevel returns nothing, as the reference notes.
- Other domains. The DN must belong to the domain you query; for another domain add
-Serverwith a domain controller of that domain (Get-ADUser -Server). - Filters still apply.
-SearchBasenarrows where,-Filternarrows what (Get-ADUser -Filter); add-Propertiesfor extra attributes (Get-ADUser -Properties). - Single user lookups use
-Identity; a wrong name fails with Cannot find an object with identity.
FAQ
How do I find the distinguished name of an OU?
Run Get-ADOrganizationalUnit -Filter 'Name -eq "Sales"' | Select-Object DistinguishedName, or copy distinguishedName from the Attribute Editor tab in Active Directory Users and Computers (with Advanced Features enabled).
Does -SearchBase work with -Identity?
No. -SearchBase and -SearchScope belong to the -Filter and -LDAPFilter parameter sets. With -Identity the cmdlet looks up one object anywhere in the domain.
Can I search several OUs at once?
Not in one call. Loop over the OUs: 'OU=Sales,DC=contoso,DC=com','OU=HR,DC=contoso,DC=com' | ForEach-Object { Get-ADUser -Filter * -SearchBase $_ }.