Tricks for Managing Active Directory with PowerShell

No matter what tools you’re using in PowerShell to enable Active Directory (AD) management, odds are you’ve run into a snag once or twice.

Both the Microsoft ActiveDirectory  module (supplied with the Windows 7 Remote Server Administration Toolkit and Windows Server 2008 R2), and the free Quest Active Directory cmdlets (downloadable from http://quest.com/powershell) have some eccentricities imposed on them by the directory itself; getting to know those little quirks will make any AD management task a bit easier.

Where Are All the Properties?

Try retrieving just a single user and you can be quickly disappointed with the data that comes back. For example:

PS C:> get-aduser DonJ

DistinguishedName : CN=DonJ,CN=Users,DC=company,DC=pri

Enabled           : False

GivenName         :

Name              : DonJ

ObjectClass       : user

ObjectGUID        : 1c6d89b1-a70b-471e-8a11-797b4569f7a1

SamAccountName    : DonJ

SID               : S-1-5-21-29812541-3325070801-1520984716-1104

Surname           :

UserPrincipalName :

Wait, that’s it? What about all of the other attributes that you just know are in the directory? Department, title, last logon date and time – there should be so much more!

As it turns out, AD doesn’t like to send over every attribute of an object by default. Doing so could potentially be a big performance hit, noticeably straining a domain controller, especially if you were trying to get a lot of attributes for a huge number of objects. To protect you from unintentionally doing that, AD only sends over a small default set of properties, and relies on you to tell it if you need other ones. With the Microsoft cmdlets, that’s done using the –Properties parameter:

PS C:> get-aduser DonJ -Properties Department,Title

Department        : IT

DistinguishedName : CN=DonJ,CN=Users,DC=company,DC=pri

Enabled           : False

GivenName         :

Name              : DonJ

ObjectClass       : user

ObjectGUID        : 1c6d89b1-a70b-471e-8a11-797b4569f7a1

SamAccountName    : DonJ

SID               : S-1-5-21-29812541-3325070801-1520984716-1104

Surname           :

Title             : CTO

UserPrincipalName :

Just make sure you specify the properties you need – or “*” if you want them all – and the directory will happily turn them over. Note that it always includes that small set of default properties, whether you ask for them or not, so you never need to explicitly ask for Name, SID, or other basic properties.

Don Jones is a Senior Partner and Principal Technologist for Concentrated Technology, LLC, an IT consulting and analysis firm. He’s the author of more than 35 books. See here for all of Don's Tom's IT Pro articles.


The Microsoft Active Directory cmdlets also try to protect you from accidentally querying too many objects, by including a mandatory –filter parameter on all “Get” cmdlets related to AD.

The idea is that you can’t just fire off Get-ADComputer and get all the computers in the domain; you have to explicitly ask for “all” by specifying Get-ADComputer –filter *. Of course, you’d ideally include something more specific to narrow down your results, such as Get-ADComputer –filter * -searchBase "ou=West,dc=domain,dc=com" which will return all computers in the West organizational unit (OU) of the domain.com domain. The –filter parameter is good for narrowing things down to a single object, or a small subset: Get-ADComputer –filter { name –eq 'CLIENT1' }is a good example. You can use –filter and –searchBase in combination, too, so that you can define a very narrow result set.

Managing Active Directory from Windows PowerShellManaging Active Directory from Windows PowerShell

There’s also a –resultSetSize parameter on most of Microsoft’s “Get” cmdlets for AD, and it defines the maximum result set size that the cmdlet will obtain for you (Quest’s cmdlets have a similar –SizeLimit parameter). The parameter does have a default value of 256, so it isn’t unlimited, meaning you will have to be sure to include the parameter and an appropriate set size value if you’re querying a large set. Otherwise, you might find your results simply truncated when the cmdlet hits its default set size. You can also set this parameter to $null to retrieve a result set of infinite size – provided you have some patience and a lot of RAM on your workstation!

If you’re familiar with the sometimes-complex LDAP filter syntax, you can opt to use the –LDAPFilter parameter on Microsoft’s cmdlets, instead of the –filter parameter. The latter accepts somewhat-easier-to-read PowerShell-style filter criteria.


It’s important to understand some of the limitations of the cmdlets that you’re using when managing Active Directory in PowerShell.

For example, the Microsoft cmdlets can talk to any domain controller running Windows Server 2003 or later. However, DCs running Win2003 or Win2008 must have the free AD Management Gateway Service installed (download it from Microsoft’s Downloads site); the service comes with Win2008R2 and later. Only one DC per domain needs to be running the service, and it should be one that’s close by whatever administrators will be managing AD. The cmdlets talk to the service, and the service talks to the actual directory.

Microsoft’s cmdlets also have a weakness related to the directory attributes they can query: Even when using –Properties *, you’ll only get back the attributes that the cmdlets and the gateway service are programmed to deal with. That unfortunately means any custom schema attributes won’t be included, and even some built-in attributes – like the ones related to Terminal Services – can’t be queried.

The Quest cmdlets don’t have either of these limitations. They can query any attribute that exists in the directory at the time, and they can talk to any AD domain controller of any version, without extra software being installed on the DCs. As you can imagine, many AD admininstrators prefer the Quest cmdlets over the Microsoft ones for their flexibility. It remains to be seen if the AD cmdlets that will ship with Windows “8” offer broader functionality in terms of querying attributes, although you can be certain they’ll continue to need the gateway service installed in order to work.

Knowing the Gotchas Will Make Things Easier!

Simply knowing these little quirks about managing AD from PowerShell will help you avoid some of the most common pitfalls. You may even find yourself using a combination of Quest and Microsoft cmdlets – something easily managed since the two sets use a different noun prefix (“QAD” for Quest, “AD” for Microsoft). And don’t forget that there’s a robust community out there willing to offer help and advice: Start at http://powershell.com/cs/forums/197.aspx, for example, where you can post questions specifically about PowerShell and AD, and have them answered by a PowerShell MVP.



.

Microsoft

You May Like

Comments