Almost all Active Directory actions that you typically carry out using tools like Active Directory Users and Computers and Active Directory Sites and Services can be carried out utilizing PowerShell. For example, you can use Active Directory PowerShell cmdlets that support specified parameters to query Active Directory data.
In order to retrieve user information from Active Directory, for instance, the Get-ADUser PowerShell cmdlet supports predefined parameters like the “-AccountExpiring” parameter, which can be used to return accounts that are about to expire in Active Directory, and the “-AccountExpired” parameter, which can be used to retrieve accounts that have already expired in the AD domain.
You can use the Get-ADObject PowerShell command to search through any object’s information in Active Directory. Even though it doesn’t offer many specified parameters, it offers a potent technique to investigate data in Active Directory.
The Get-ADObject PowerShell cmdlet is explained in this article along with several practical examples to show you how to use it to speed up your Active Directory searches.
Table Of Contents
-
Prerequisites/Requirements
-
Get-ADObject – Description
-
Get-ADObject – Syntax
-
Get-ADObject – Parameters
-
Three Most Used Parameters with Get-ADObject
-
Understanding the Identity Parameter
-
Understanding the Filter Parameter
-
Understanding the LDAPFilter Parameter
-
Get the Results to a CSV File (Export-CSV)
-
Conclusion
Prerequisites/Requirements
The use of Get-ADObject will be demonstrated in this article. Make sure you have the following prerequisites in place if you intend to follow along:
- An Active Directory domain environment based on Windows server 2012 or higher.
- A Windows server or client operating system joined to the Active Directory domain environment.
- A privileged domain account that can perform the required operations in the domain via PowerShell.
- Remote Server Administration Tools (RSAT) package installed if the workstation is a standalone server or client operating system (e.g., Windows 10).
- Be sure to import the Active Directory module in PowerShell; otherwise you will run into errors indicating that the cmdlet is not recognized.
Get-ADObject – Description
Function
The primary function of the Get-ADObject cmdlet is to connect to an AD domain controller or Lightweight Directory Service (LDS) server and retrieve data about various Active Directory objects.
The Get-ADObject cmdlet includes several parameters that you may use to query AD objects, including connecting to several domain controllers, searching a global catalog, authenticating with different credentials, specifying LDAP filters, and limiting the items returned by the scope for set for SearchBase.
Working
The Get-ADObject cmdlet retrieves a single Active Directory object or several objects using a search.
- Retrieving a single objectThe Active Directory object to retrieve is specified by the Identity option. By using an object’s distinctive name or GUID, you can determine the object you want. You can also feed an object via the pipeline to the Identity parameter or assign the parameter to an Active Directory object variable, such as $Variable.
- Retrieving multiple objectsThe Filter or LDAPFilter parameter can be used to look for and retrieve multiple objects. With the Filter option, you can write query strings for Active Directory using the PowerShell Expression Language. Value types obtained by the Filter parameter are supported for rich type conversion in PowerShell Expression Language syntax. The LDAPFilter parameter can be used if your Lightweight Directory Access Protocol (LDAP) query strings already exist.
Default count for returned objects:
The Get-ADObject cmdlet by default only returns 1000 AD objects. To get a maximum number of objects, you can define the ResultSetSize parameter.
Get-ADObject – Syntax
Below is a typical example of the Get-ADObject cmdlet syntax. Here, we have used the following three main parameters to search the logical sites in the Active Directory domain environment, representing the physical sites in an organization’s operations worldwide.
- -LDAPFilter
- -SeachBase
- -Properties
Get-ADObject -LDAPFilter "(objectClass=site)" -SearchBase 'CN=Configuration,DC=Fabrikam,DC=Com' -Properties CanonicalName | FT Name,CanonicalName
Get-ADObject – Parameters
Some parameters used by the Get-ADObject cmdlet are:
- -AuthType: Used to assign the authentication method in the cmdlet as Basic or Negotiate.
- -Credential: Used to provide alternate credentials if required.
- -Identity: Used to get the object the actions need to be performed on. Supported values are SID, GUID, SAM Account name, Distinguished Name, etc.
- -IncludeDeletedObjects: Used to indicate deleted objects and deactivated forward or backward links.
- -Filter: Most powerful parameter though, you can use it to specify any PowerShell Expression Language. For example, -eq (equals to) or -ne (not null).
- -LDAPFilter: Provides an LDAP query string for filtering Active Directory objects. You can execute your current LDAP queries using this option.
- -Properties: Specifies the output object’s properties that the server should return with the cmdlet. To obtain properties that are not part of the default set, use this parameter.
- -Partition: Use this parameter to specify an Active Directory partition distinguished name, to get the results from the that specific partition.
- -ResultPageSize: Used to define the number of objects to show in one page of an AD DS query.
- -ResultSetSize: Use this parameter to get the maximum number of objects to return from the server.
- -SearchBase: Used to set the path as an OU distinguished name to return the searches.
- -SearchScope: Used to define the sub-level of OUs from which you want to return the results. Values are: (Base or 0, OneLevel or 1, Subtree or 2).
- -Server: Used to specify the instance of an AD DS 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.
Three Most Used Parameters with Get-ADObject
The following parameters are commonly used with Get-ADObject:
- -Identity
- -Filter
- -LDAPFilter
In fact, these parameters are used with almost all the PowerShell cmdlets used to query Active Directory objects. Those objects include, users, groups, computers, Active Directory sites, contacts, and any other type of objects.
In this article, we will use these three parameters frequently with other parameters to get the desired results.
Understanding 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. A non-terminating error is returned if two or more objects are discovered.
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 lists some common properties of the object that was given a value after the “-Identity” parameter. Get-ADObject understands that it needs to retrieve properties for a particular object from the Active Directory database since you provided the object name. We have also provided the -Server parameter to narrow the scope from the directory to a specific directory server.
Understanding the Filter Parameter
The Filter parameter is a powerful parameter. You can use its multiple logical operators to get almost any kind of result supported by the main cmdlet. Following are the operators and examples used by the Filter parameter.
List of Operators for the Filter Parameter
| Operator | Meaning | Sample expression |
|---|---|---|
| -eq | Equal to | Name -like ‘Inga’ |
| -ne | Not equal to | Country -ne ‘US’ |
| -gt | Greater than | BadLogonCount -gt ‘0’ |
| -ge | Greater than or equal | Modified -ge ’06-04-2021 12:00:00′ |
| -lt | Less than | LastLogonTimeStamp -lt ’01-08-2020′ |
| -le | Less than or equal | Created -le ’01-08-2020′ |
| -like | Wildcard search | Mail -like ‘*@xyz.com’ |
| -notlike | Wildcard search with negation | Department -notlike ‘*’ |
| -and | And | Country -eq ‘US’ -and Department -eq ‘Operations’ |
| -or | Or | Country -eq ‘US’ -or -Country -eq ‘UK’ |
The simplest example of the Filter parameter is to be used with a wild card (*), as shown below:
Get-ADObject -Filter *
When using the Filter parameter with wild card, make sure you use other parameters too, as it will bring all the results in the domain if not used for a specific OU or object type.
Get Computer Objects from Active Directory (Filter)
Using the filters listed below, you can retrieve computer objects from Active Directory.
Get-ADObject -Filter {(objectClass -eq "user") -and (objectCategory -eq "computer")}
Notice in the screenshot that two filters are used in the Get-ADObject cmdlet:
- One filter is used to define the object class, which is user, as the computers object also falls under the user object class.
- We have used another filter as object category to bring computer objects only.
This example also contains the -and operator to combine two or more filter operators.
Get Users Objects only (Filter)
Use the same filter that you used for computer objects to get all the users from the domain. Remember to change the object category to user, as shown below:
Get-ADObject -Filter {(objectClass -eq "user") -and (objectCategory -eq "user")}
The distinguished name, user name, object class, and object GUID are the results of the command.
Get AD Objects from a Specific OU (SearchBase)
Using the SearchBase parameter with the Filter parameter will get you all the desired objects from a specific OU. The SearchBase parameter accepts value in the form of the Distinguished Name of the OU. It is as:
Get-ADObject -Filter * -SearchBase 'OU=NBC,DC=milkyway,DC=local'
Find Active Directory Contacts (Filter)
Similarly, you can use filter as object class equals to contacts and get the contact objects from Active Directory.
We have used the Properties filter in the following cmdlet to also show the CN of the contacts.
Get-ADObject -Filter 'objectClass -eq "contact"' -Properties CN | Format-List CN
Find AD User Name using SID (Filter)
You can also use an AD user’s SID (security identified) to show his/her properties (e.g., name, sam account name, user principal name) in the following script:
$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 then passes the output to the Select-Object cmdlet. The second cmdlet then prints the required properties of the object returned against the SID.
Understanding the LDAPFilter Parameter
You can further filter Active Directory objects using -LDAPFilter by providing an LDAP query string. 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. You must utilize the “ObjectClass” schema attribute, for instance, to search for all Active Directory sites in Active Directory. All Active Directory objects with the ObjectClass property set to “Site” are listed using the following PowerShell command:
Get-ADObject –LDAPFilter "(ObjectClass=Site)" –SearchBase "CN=Configuration,DC=Virgo,DC=Local"
With this command, all Active Directory sites and their associated properties are retrieved.
Similarly, if you want to retrieve a list of organizational units that have been created in Active Directory, you must specify “ObjectCategory” as “OrganizationalUnit”. It is as shown in the following command:
Get-ADObject –LDAPFilter "(ObjectCategory=OrganizationalUnit)" –SearchBase "DC=Virgo,DC=Local"
Before retrieving data using Get-ADObject, you must first get familiar with the -LDAPFilter parameter, which requires working knowledge of LDAP strings. The PowerShell command shown below only displays computer objects whose primary group is the “Domain Controllers” security group.
Get-ADObject –LDAPFilter "(&(ObjectCategory=Computer)(PrimaryGroupID=516))" –SearchBase "DC=Virgo,DC=Local"
The following command should be used if you need to obtain global groups from Active Directory:
Get-ADObject –LDAPFilter "(GroupType:1.2.840.113556.1.4.803:=2)" –SearchBase "DC=Virgo,DC=Local"
Get the Results to a CSV File (Export-CSV)
If you want to get the output of any cmdlet in the form of CSV, use the Export-CSV cmdlet with a file name destination. You can simply pipe this cmdlet in between a PowerShell script or at the end of any cmdlet, as shown below:
Get-ADObject -Filter 'objectClass -eq "container"' | Export-Csv -Path C:\TestFolder\containers.csv
When you use the Export-CSV cmdlet, it doesn’t show any results in the PowerShell console, but exports them to a CSV file. You can open .CSV files with Microsoft Excel to see the output in the form of clear rows and columns.
Below are some more examples of the above used filter cmdlets:
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
In this blog, we have discussed the Get-ADObject cmdlet with parameters and examples, such as how to use the three most widely known parameters, Identity, Filter and LDAP Filter, along with other helping parameters like SearchBase to bring results from specific OUs. Then we have shown examples of exporting the results to a csv file.
Jonathan Blackwell
View ProfileSince 2012, Jonathan Blackwell, an engineer and innovator, has provided engineering leadership that has put GroupID at the forefront of group and user management for Active Directory and Azure AD environments. His experience in development, marketing, and sales allows Jonathan to fully understand the Identity market and how buyers think.