Find Users with Get-ADUser

Over the 11 years that Active Directory (AD) has been around, we’ve seen a number of automation tools that can extract subsets of AD, and I’ve written about many of them in this space. The latest in that line—Get-ADUser—is a member of Windows Server 2008 R2’s 76-cmdlet PowerShell team. It’s a strong tool that every AD administrator should start using, so it’s the focus of this month’s column.

Related: Digging Deeper into Get-ADUser

Essentially, all you’ll need in order to run Server 2008 R2’s AD cmdlets is at least one Windows 7 or Server 2008 R2–based member server (from which to issue the commands) and at least one Server 2008 R2–based domain controller (to receive and execute the commands). I say “essentially” because you can actually get a pre–Server 2008 R2 DC to understand PowerShell commands, but that’s a long story for another day.

To start finding user objects with Get-ADUser, open a PowerShell window and import the AD module by typing import-module activedirectory, or its shortened version, ipmo ac*. If you’ve ever used a PowerShell cmdlet that starts with get- (e.g., get-process, get-service), you might imagine that you could simply type

get-aduser  

and then PowerShell would show you all the users, but that doesn’t happen. Rather, PowerShell prompts you for some parameters. The parameter you’ll use most commonly is -filter, which lets you insert criteria for picking out the users you want. The most basic one is

get-aduser -filter *

which tells PowerShell to retrieve every user account in your AD implementation. I highly recommend that you do not run that command on your production network unless it’s very small or you don’t mind overloading your local DC. I recommend getting pickier, as in this example that finds all users whose first names are Mark:

get-aduser -f {GivenName -eq 'Mark'}

If you run that command on a network that lacks anyone named Mark, PowerShell will return a prompt with no explanatory text. That example raises a number of concerns, however, so let me provide a few explanatory notes.

First, notice that I typed -f, not -filter. PowerShell lets you abbreviate any parameter name as much as you want, as long as the abbreviation doesn’t create ambiguity. The only parameter that starts with the letter f is -filter, which is why you can shorten it down to -f. But if this cmdlet had a -finger parameter, for example, -f would be too ambiguous and I wouldn’t be able to abbreviate it smaller than -fil.

Second, what’s with GivenName? The names of AD user attributes come from the X.500 standard schema, and—for whatever reason—the folks who cooked up X.500 chose to use the more European-ish phrase GivenName (rather than, say, firstname). If you’ve used ADSI Edit, you already know this, but what you might not know is that the folks who wrote the AD cmdlets took things further by offering multiple versions of some attributes. For example, the X.500 phrase for last name is sn, which is short for surname. (Don’t ask me why the X.500 folks didn’t use gn as the attribute for first name!) Anyway, you’ll find that PowerShell cmdlets recognize both sn and the non-standard surname as valid user attributes. You can, however, easily see a complete list of attributes that user Mark has, like so:

get-aduser -f {name -eq 'Mark'} -properties *| get-member

Save that command’s output somewhere because it will be a useful listing of the layout of AD user objects and thus will simplify crafting queries in the future.

Third, you’ve probably guessed that -eq is PowerShell-speak for is equal to. You can’t use an equals sign in your queries, so -f {name = 'Mark'} wouldn’t fly. You might be surprised, however, that the following won’t work either (or at least not the way you’d expect):

get-aduser -f {name -eq 'M*'}

PowerShell draws a distinction between comparisons containing wildcards and comparisons that don’t contain wildcards. For an exact-match test, use -eq. For one incorporating a wildcard, use -like, as in

get-aduser -f {name -like 'M'}

I’ve been comparing name to Mark with a capital letter, but I should mention that the AD PowerShell cmdlets are case-insensitive. PowerShell experts might know that you can, in general, specify case-sensitive comparisons by using the -ceq operator instead, but note that you can’t do that with the AD cmdlets. There’s no -ceq support there.

Querying on a first name is, of course, a pretty simple query. Next month, I’ll show you some more in-depth queries.