Get the most out of PowerShell AD queries
In “Find Users with Get-ADUser,” I introduced you to Get-ADUser, a handy Windows Server 2008 R2 tool that’s certainly in the top five of the new OS’s new Active Directory (AD) cmdlets. This month, I want to dive further into the tool and show you how to get the most out of PowerShell AD queries.
Consider this query, which is similar to one I’ve used in past columns:
get-aduser -f {givenname -like 'M*'}
This query returns all users whose first name begins with M. Recall that you could’ve discovered that givenname is a legal thing to search on by doing a simpler search and asking PowerShell to reveal the structure of the contents of that search by piping the output to get-member, like this:
get-aduser -f * -properties * | get-member
Armed with that information, you might see that you could retrieve all the people whose primary group membership lay with the Domain Admins group with this query, assuming an AD name of bigfirm.com:
get-aduser -f {primarygroup -eq 'CN=domain admins,cn=users,dc=bigfirm,dc=com'}
Here's how I knew that. After running the get-member command, I saw a list of the 114 (on my domain) attributes of an AD user, and I noticed a PrimaryGroup attribute. I assumed that I'd have to type it as an LDAP-format name, but I wasn't certain, so I just asked to see it on my user account by using the query we've already seen—but with a more specific -properties parameter:
get-aduser -f {givenname -eq 'Mark'} -pr PrimaryGroup
I got some output that included
PrimaryGroup : CN=Domain Users,CN=Users,DC=bigfirm,DC=com
And so I saw that forming a query to find the "primary administrator" types would be easy. (By the way, if you run this on a fairly vanilla AD implementation, you won't get any results, as no one's primary group is set to Domain Admins by default. And no, this wasn't the most efficient way to get the PrimaryGroup information, but it worked, and that's important: If you're not willing to explore PowerShell a bit, you'll never really get comfy with it.)
By the way, in our never-ending struggle to minimize keystrokes, did you notice that I typed -pr rather than -properties? A couple months ago, I explained how parameter shortening works—that's how I knew I could trim it to -pr. But recall another sort of shortening that you might have noticed in “Go Remote with Windows Server 2008 R2’s AD Cmdlets” (InstantDoc ID 140491). In that article, I said that you could shorten enter-pssession to etsn. How did I know that? Simple: I used a cmdlet named get-alias, which works like so:
get-alias -def enter-pssession
Alias is PowerShell-ese for "alternate shorter command name that's just as good as the 'official' long name." Try that out for get-member, and you'll learn that it has an alias of gm. Unfortunately, the AD team didn't assign an alias to Get-ADUser—my vote is for gadu—and though you can create your own aliases, it's generally nt suc a gud idea, as nonstandard abbreviations tend to make things hard to read.
The AD PowerShell team took the time to build Get-ADUser parameters for every one of the 100-plus user attributes (thanks!), so you can even do queries on things as obscure as
get-aduser -f {physicaldeliveryofficename -eq 'Downtown'}
Blame that one on the X.500 guys, by the way, but take heart in the fact that in that case, the PowerShell AD folks created another parameter, -office, that points to the same attribute but involves a bit less typing.
But what about a more complex query? Thus far, we've searched on attributes, but sometimes we're less interested in identifying an AD object via its attributes than we are in identifying the object by its location. For example, suppose one of bigfirm.com's organizational units (OUs) is a geographical one named Pungo, which is one of Bigfirm's offices. Let's also suppose we need to create a query that collects all the AD user objects located in the Pungo OU (in LDAP-ese, ou=pungo,dc=bigfirm,dc=com). How do we grab all those folks? I've tried querying on the DistinguishedName of the object, using -like to compare it with * ou=pungo,dc=bigfirm,dc=com, but I didn't get any matches, so it's a good thing we've got the -searchbase parameter. Include it and the distinguished name of any container objects in AD in the Get-ADUser command (and, for that matter, most of the Server 2008 R2 AD-related PowerShell cmdlets), and you'll restrict the search to just that container. So, for example, to return only the users in Bigfirm's Pungo OU, you could type
get-aduser -f * -searchbase "ou=pungo,dc=bigfirm,dc=com"
Thus, if we wanted to find everyone in the Pungo OU who has a Gmail account, we could type
get-aduser -f {emailaddress -like "*@gmail.com"} -searchbase "ou=pungo,dc=bigfirm,dc=com"
That's not a bad little query, but PowerShell can do much more complex ones, as you'll see next month.