Get-AdUser is our first PowerShell cmdlet for the day!

If you're in IT, chances are you've got some implementation of Microsoft's Active Directory (AD). A huge part of AD is users. Users are what gets assigned to individual employees, service accounts, etc. Get-AdUser is a cmdlet inside of the freely available Remote Server Administration Tools (RSAT) package. If you're on Windows 10, you can install RSAT by running Install-WindowsFeature RSAT-AD-PowerShell in a PowerShell console.

Once you have the ActiveDirectory module installed, let's take a look at the cmdlet we're here for today!

Get-AdUser has one purpose and one purpose only: to give you as many options as possible to either find a specific user object where you already know information about or return lots of users that match specific criteria. Unlike local users you may find in the a Windows PC's security account manager (SAM) database, AD users contain a host of attributes.

Finding a User Account

If you already know a couple different criteria for a user object already Get-AdUser allows you to identify a user. To do so requires knowing one of four unique user identifiers:

  • distinguishedName
  • samAccountName
  • GUID
  • SID
  • name

The Identity parameter is flexible on the Get-AdUser cmdlet as well as many of the other ActiveDirectory module cmdlets.

PS> Get-ADUser -Identity abertram


DistinguishedName : CN=Anne Bertram,OU=Marketing,DC=mylab,DC=local
Enabled           : False
GivenName         : Anne
Name              : Anne Bertram
ObjectClass       : user
ObjectGUID        : b98fd0c4-3d5d-4239-8245-b04145d6a0db
SamAccountName    : abertram
SID               : S-1-5-21-4117810001-3432493942-696130396-3142
Surname           : Bertram
UserPrincipalName : [email protected]



PS> Get-ADUser -Identity 'S-1-5-21-4117810001-3432493942-696130396-3142'


DistinguishedName : CN=Anne Bertram,OU=Marketing,DC=mylab,DC=local
Enabled           : False
GivenName         : Anne
Name              : Anne Bertram
ObjectClass       : user
ObjectGUID        : b98fd0c4-3d5d-4239-8245-b04145d6a0db
SamAccountName    : abertram
SID               : S-1-5-21-4117810001-3432493942-696130396-3142
Surname           : Bertram
UserPrincipalName : [email protected]



PS> Get-ADUser -Identity 'CN=Anne Bertram,OU=Marketing,DC=mylab,DC=local'


DistinguishedName : CN=Anne Bertram,OU=Marketing,DC=mylab,DC=local
Enabled           : False
GivenName         : Anne
Name              : Anne Bertram
ObjectClass       : user
ObjectGUID        : b98fd0c4-3d5d-4239-8245-b04145d6a0db
SamAccountName    : abertram
SID               : S-1-5-21-4117810001-3432493942-696130396-3142
Surname           : Bertram
UserPrincipalName : [email protected]

You'll find that the most common attribute to use for the Identity parameter will be the samAccountName attribute.

Finding Users Based Off of Filters

If you don't know any of the four attribute values for the Identity parameter or need to return potentially many users that match specific criteria, you've got quite a couple options: Filter and LDAPFilter.

If you know LDAP syntax well, check out LDAP filter. The LDAPFilter parameter allows you to use LDAP queries that have worked a long time now. For a full reference of the LDAPFilter string, check out Advanced LDAP Filters that go into great detail on this one.

Or, you can use the more common ActiveDirectory Filter parameter. This parameter is a little easier to use because it uses a different syntax although some may say it's still not the easiest to use especially when we're used to the Where-Object cmdlet's filter syntax!

The Filter parameter uses a language called PowerShell expression language syntax which is a bit awkward to learn but once you get the hang of it, it's not too bad.

Here's an example of using the Filter string of givenName -eq 'Adam to find all accounts with a givenName of Adam.

PS> Get-AdUser -Filter "givenName -eq 'Adam'"


DistinguishedName : CN=ADBertram,OU=Accounting,DC=mylab,DC=local
Enabled           : False
GivenName         : Adam
Name              : ADBertram
ObjectClass       : user
ObjectGUID        : 8ec5e2a8-1fda-42cb-9406-b1e6356dd457
SamAccountName    : ADBertram
SID               : S-1-5-21-4117810001-3432493942-696130396-3163
Surname           : Bertram
UserPrincipalName : ADBertram

DistinguishedName : CN=Hughes\, Adam,CN=Users,DC=mylab,DC=local
Enabled           : True
GivenName         : Adam
Name              : Hughes, Adam
ObjectClass       : user
ObjectGUID        : 96778db3-3dbd-4b83-9183-db111caa2791
SamAccountName    : ahughes
SID               : S-1-5-21-4117810001-3432493942-696130396-38201
Surname           : Hughes
UserPrincipalName :

Like the LDAP filter, the Filter parameter has numerous options available that are too many to discuss in depth here but this great article on TechNet covers so much of the filter syntax in depth.

Finding Users Under an OU

The Get-Aduser cmdlet has a parameter called SearchBase that allows you to begin searching for a user account in a specific OU. By default, this will search the specified OU and all child OUs.

For example, we could find all users in the MyUsers OU as shown below.

PS> Get-ADUser -Filter * -SearchBase 'OU=MyUsers,DC=domain,DC=local'

Perhaps we only want to find user accounts in a single OU and exclude any child OUs. In that case, we could use the SearchBase parameter to start searching at a particular OU and also use the SearchScope parameter which will limit the child OUs that are searched.

To limit the search to only the OU specified with SearchBase, you would use a SearchScope parameter of Base or 0 as shown below.

PS> Get-ADUser -Filter * -SearchBase 'OU=MyUsers,DC=domain,DC=local' -SearchScope Base

You can also pass the SearchScope parameter values such as OneLevel or 1 to indicate the base OU and immediate children or Subtree or 2 which will search the current OU path and all child OUs recursively.

Using Alternate Credentials

By default, Get-AdUser will run under the context of the logged-on user but you can also provide alternative credentials using the Credential parameter.

To authenticate to AD with alternate credentials, you first need to create a PSCredential object using Get-Credential like below:

PS> $cred = Get-Credential
PS> Get-AdUser -Filter * -Credential $cred

Using the Property Parameter

When Get-AdUser is run, you'll immediately see only a few attributes are returned. You'll also see that even when the output is piped to Select-Object -Property * even all of the attributes aren't returned. This is an oddity with a lot of the AD cmdlets.

Instead, you'll need to use the Property parameter and specify the attributes you'd like to see or simply use an asterisk to see them all.

PS> Get-AdUser -Filter "givenName -eq 'Adam'" -Properties *


AccountExpirationDate                :
accountExpires                       : 9223372036854775807
AccountLockoutTime                   :
AccountNotDelegated                  : False
AllowReversiblePasswordEncryption    : False
AuthenticationPolicy                 : {}
AuthenticationPolicySilo             : {}
BadLogonCount                        : 0
badPasswordTime                      : 0
badPwdCount                          : 0
CannotChangePassword                 : False
CanonicalName                        : mylab.local/Accounting/ADBertram
........

For a full breakdown of Get-AdUser and all of it's parameters, check out the help content by running Get-Help Get-AdUser.

For many examples of how to use Get-AdUser, check out the blog post Active Directory Scripts Galore: Come and Get It!.

Join the Jar Tippers on Patreon

It takes a lot of time to write detailed blog posts like this one. In a single-income family, this blog is one way I depend on to keep the lights on. I'd be eternally grateful if you could become a Patreon patron today!

Become a Patron!