Introduction
The Get-ADUser PowerShell cmdlet provides an easy way to retrieve user information from Active Directory. For example, you can quickly get a list of all AD accounts that are about to expire or that have already expired.
This article provides the syntax of this cmdlet and then provides a deep dive into the three most commonly used parameters.
Get-ADObject: Description
The Get-ADObject cmdlet connects to an AD domain controller or Lightweight Directory Service (LDS) server and retrieves data about one or more Active Directory objects:
- Retrieving a single object — To retrieve information about a specific AD object, you can either specify the object using Identity parameter, use a pipeline to feed the object to the Identity parameter, or assign the Identify parameter to an AD object variable.
- Retrieving multiple objects — To retrieve multiple objects, you can use the Filter parameter to specify query strings, or use the LDAPFilter parameter if your query strings already exist.
Get-ADObject: Syntax
The syntax of the Get-ADObject cmdlet is as follows:
New-ADObject [-Name] <string> [-Type] <string> [-WhatIf] [-Confirm] [-AuthType <ADAuthType>] [-Credential <pscredential>] [-Description <string>] [-DisplayName <string>] [-Instance <ADObject>] [-OtherAttributes <hashtable>] [-PassThru] [-Path <string>] [-ProtectedFromAccidentalDeletion <bool>] [-Server <string>] [<CommonParameters>]Following is an example of the Get-ADObject cmdlet syntax that uses three of its parameters:
Get-ADObject -LDAPFilter "(objectClass=site)" -SearchBase 'CN=Configuration,DC=Fabrikam,DC=Com' -Properties CanonicalName | FT Name,CanonicalName
Get-ADObject: Parameters
Here are some key parameters to know about.
Top 3 Parameters
The three most commonly used parameters of the Get-ADObject cmdlet are:
- -Identity: Specifies a specific object to be retrieved using a unique identifier such as its distinguished name, SID or GUID
- -Filter: Used to specify a query in PowerShell Expression Language for selecting AD objects
- -LDAPFilter: Used to specify an LDAP query string for selecting AD objects
The following sections explore these three parameters in more detail.
Other Useful Parameters
Other useful parameters include:
- -AuthType: Used to assign the authentication method (Basic or Negotiate)
- -Credential: Used to provide alternate credentials for executing the cmdlet
- -IncludeDeletedObjects: Used to include deleted objects and deactivated links in the results
- -Properties: Specifies any object properties that should be returned from the server in addition to the default properties (to get a list of the default set of properties of an AD object, use the following command: Get-ADObject<object>| Get-Member)
- -Partition: Limits the search to the specified Active Directory partition
- -ResultPageSize: Defines the number of objects to show on each page
- -ResultSetSize: Specifies the maximum number of objects to be returned (1,000 by default)
- -SearchBase: Specifies the Active Directory path (OU) to search
- -SearchScope: Defines how many sub-levels of the OU to search: (Base or 0, OneLevel or 1, Subtree or 2)
- -Server: Specifies the AD DS instance to bring the results from. Values can be the fully qualified domain name or NetBIOS name of the server. You can also use port with FQDN.
Using the Identity Parameter
The Identity parameter is used to get the object on which the cmdlet performs further actions. The cmdlet looks into the default partition or naming context to find the object. If two or more objects are discovered, a non-terminating error is returned.
The value for this parameter is most often a distinguished name, but other common properties like name, samAccountName and GUID can also be used.
Get-ADObject –Identity “AbbeyCrawford” –Server “dcexch2013.milkyway.local”
The command above also uses the -Server parameter, which narrows the scope from the directory to a specific directory server.
Using the Filter Parameter
The Filter parameter is quite powerful — you can specify a complex query string to retrieve the desired AD objects.
Operators for the Filter Parameter
| Operator | Meaning | Example |
| -eq | Equal to | Name -eq ‘Inga’ |
| -ne | Not equal to | Country -ne ‘US’ |
| -gt | Greater than | BadLogonCount -gt ‘0’ |
| -ge | Greater than or equal | Modified -ge ’06-04-2022 12:00:00? |
| -lt | Less than | LastLogonTimeStamp -lt ’01-08-2021? |
| -le | Less than or equal | Created -le ’01-08-2020? |
| -like | Matching a wildcard pattern | Mail -like ‘*@xyz.com’ |
| -notlike | Not matching a wildcard pattern | Department -notlike ‘*’ |
| -and | And | Country -eq ‘US’ -and Department -eq ‘Operations’ |
| -or | Or | Country -eq ‘US’ -or -Country -eq ‘UK’ |
Example 1: Get AD Computer Objects
To retrieve computer objects from Active Directory, use the following command:
Get-ADObject -Filter {(objectClass -eq "user") -and (objectCategory -eq "computer")}
Notice that this example uses the -and operator to specify two filters:
- The first define the object class (which is user, as the computer objects fall under the object class user).
- The second uses object category to limit the results to computer objects.
Example 2: Get AD User Objects
We can use the same filter that you used for computer objects to get information about all the users in the domain simply by changing the object category to user:
Get-ADObject -Filter {(objectClass -eq "user") -and (objectCategory -eq "user")}
Notice that output shows the distinguished name, user name, object class, and GUID of each AD user.
Example 3: Get AD Objects from a Specific OU
To get objects from a specific OU, use the -SearchBase parameter to specify the OU’s distinguished name:
Get-ADObject -Filter * -SearchBase 'OU=NBC,DC=milkyway,DC=local'
Example 4: Find Active Directory Contacts
To get contact objects, change the object class to contact. Here we also use the -Properties parameter to include the CN of each contact in the output:
Get-ADObject -Filter 'objectClass -eq "contact"' -Properties CN | Format-List CN
Example 5: Find an AD User by Assigning a SID to a Variable
Here, we assign a user’s SID (security identifier) to the variable $ObjectSid and use it to retrieve selected properties of that user:
$ObjectSid = 'S-1-5-21-2144973983-3571309751-2556536001-2005'
Get-ADObject -Filter "objectSid -eq '$ObjectSid'" -Properties * | Select-Object name,distinguishedname,samaccountname,userprincipalname
In the above script, the SID of a user account is stored in the $ObjectSID variable. The Get-ADObject cmdlet uses the filter operator -eq to query $ObjectSID and passes the output to the Select-Object cmdlet. The second cmdlet then prints the required properties of the object returned against the SID.
Using the LDAPFilter Parameter
The LDAPFilter parameter is similar to the Filter parameter, with the exception that you must utilize an Active Directory schema property to retrieve the necessary data.
Example 1: List All AD Sites
You must utilize the “ObjectClass” attribute, for instance, to search for all sites in Active Directory. For example, the following command will list all Active Directory sites and their associated properties:
Get-ADObject –LDAPFilter “(ObjectClass=Site)” –SearchBase “CN=Configuration,DC=Virgo,DC=Local”
Example 2: List All OUs
Similarly, to retrieve a list of OUs, you must specify “ObjectCategory” as “OrganizationalUnit”.
Get-ADObject –LDAPFilter "(ObjectCategory=OrganizationalUnit)" –SearchBase "DC=Virgo,DC=Local"
Example 3: List All DCs
The following command will display computer objects whose primary security group is Domain Controllers by using that group’s PrimaryGroupID (516):
Get-ADObject –LDAPFilter "(&(ObjectCategory=Computer)(PrimaryGroupID=516))" –SearchBase "DC=Virgo,DC=Local"
Example 4: List Global Groups
Use the following command to obtain information about global groups:
Get-ADObject –LDAPFilter "(GroupType:1.2.840.113556.1.4.803:=2)" –SearchBase "DC=Virgo,DC=Local"
Exporting Results to a CSV File
To export the output of any PowerShell cmdlet to a CSV file instead of showing it in the PowerShell console, simply pipe the results to the Export-CSV cmdlet with a file name destination, as shown below:
Get-ADObject -Filter 'objectClass -eq "container"' | Export-Csv -Path C:\TestFolder\containers.csv
Additional Examples
Below are some additional examples of the Get-ADObject cmdlet with the parameters discussed earlier and the results as they appear in Excel:
Get-ADObject –LDAPFilter "(ObjectClass=Site)" –SearchBase "CN=Configuration,DC=Virgo,DC=Local" | Export-Csv -Path C:\TestFolder\sites.csv
Get-ADObject –LDAPFilter "(&(ObjectCategory=Computer)(PrimaryGroupID=516))" –SearchBase "DC=Virgo,DC=Local" | Export-Csv -Path C:\TestFolder\computer.csv
Get-ADObject –LDAPFilter "(GroupType:1.2.840.113556.1.4.803:=2)" –SearchBase "DC=Virgo,DC=Local" | Export-Csv -Path C:\TestFolder\GlobalGroups.csv
Get-ADObject –LDAPFilter "(ObjectCategory=OrganizationalUnit)" –SearchBase "DC=Virgo,DC=Local" | Export-Csv -Path C:\TestFolder\OrganizationalUnits.csv
Conclusion
The Get-ADObject cmdlet is a powerful tool for retrieving information about Active Directory objects. Be sure to try out the three parameters described here — Identity, Filter and LDAPFilter — for yourself, along with parameters like SearchBase to limit the search to specific OUs. You will quickly learn how to create commands to retrieve the information you need in many different situations.
