Windows PowerShell

Windows PowerShell 2.0 Brings Scripting to Active Directory — and Not Just for Windows Server 2008 R2

Don Jones

Sometimes, it seems like Microsoft can take forever to produce the solutions we need. I mean, tens of thousands of worldwide employees, and still no “Halo 4”? But sometimes, the wait is simply because it’s trying to produce the right solution — and in the case of Active Directory scripting and automation, the wait has paid off. Windows Server 2008 R2 ships with a Windows PowerShell 2.0 module that enables fantastic scripting and automation for Active Directory.

System Requirements: Truths & Myths

The new Active Directory commands for Windows PowerShell do require Windows PowerShell v2. The commands are distributed in a module, which is new to 2.0, rather than as a PSSnapin. Modules are easier to distribute and don’t require installation or registration—you simply copy their files to the shell’s Modules folder and use the Import-Module command to bring the module into the shell.

Windows PowerShell 2.0 is preinstalled in Windows 7 and Windows Server 2008 R2; it should be available for Windows Server 2008, Windows Vista, Windows XP and Windows Server 2003 sometime near the end of 2009 or early 2010. The Active Directory module comes with Windows Server 2008 R2, but it’s a myth that you have to have every domain controller (DC) in your environment running that OS in order to use the commands. In fact, the commands will work fine against a Windows Server 2003 DC and a Windows Server 2008 (non-R2) DC—provided you install the free Active Directory Management Gateway Service (download from microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=008940c6-0296-4597-be3e-1d24c1cf0dda) on those DCs. The Gateway Service is what the Active Directory commands talk to, and the service can be installed on Windows Server 2003 R2 SP2 and later, or Windows Server 2008 SP2 or later.

For now, your client computer needs to be running Windows 7 or Windows Server 2008 R2, because it is not currently possible to install the Active Directory module on anything older.

Authentication

One of the tricky bits of working with Active Directory is authentication: You may want to manage a domain other than the one you log into, and you may not have trusts between all of the domains that you want to manage. In some cases, you may have administrative rights in another domain, but only through an alternate user account. Windows PowerShell 2.0 doesn’t provide a built-in mechanism for persisting all those different credentials, and so the folks who wrote the Active Directory module had to come up with a technique. What they designed is as elegant as it is easy: The Active Directory module includes a Windows PowerShell PSDrive provider, meaning you can “map a drive” to an Active Directory domain. That drive mapping contains your credentials, and it enables those credentials to persist for the duration of your shell session. When the module loads into the shell, it automatically maps your login domain, using whatever credentials you used to run Windows PowerShell 2.0 (caution: User Account Control applies, so be sure to run the shell “as Administrator” if that’s what you need to do). To map new domains, use the New-PSDrive cmdlet, which supports command-line parameters for specifying credentials.

To change directories into a mapped domain, use the familiar Cd command: Cd AD:, for example,  changes the shell’s focus into the domain mapped by default. Changing into the domain is critical, because all of the Active Directory commands will, by default, use the credentials of whatever domain the shell is focused on at the time. It’s a really neat trick, allowing you to run Active Directory commands without having to manually specify credentials each time. Need to run the same command against another domain? Just change to that domain, hit the up arrow a couple of times to recall the Active Directory command, and hit Enter to run it again in the new domain.

The Active Directory commands don’t force you to work that way, though: Each of them also supports the command-line parameters needed to specify credentials on a case-by-case basis. So you can work whichever way you choose, a flexibility that I very much appreciate. The product team could have easily selected one technique or another, and the fact that they included both is an acknowledgement of the diversity of their audience.

The Commands

All told, the Active Directory module brings 82 new commands into the shell, ranging from obvious like New-ADUser to the more esoteric, like Install-ADServiceAccount. All of the cmdlets have an “AD” prefix, which performs two important functions. First, it helps distinguish the cmdlets from other similar ones—New-ADUser creates a new AD user, not a new local user or a new SQL Server user or something else. Second, the prefix helps you find all of the cmdlets easily: Run Help *–AD* and you’ll get a list of all 82.

Each of the Active Directory commands has command-line parameters—lots of parameters, in some cases. New-ADUser, for example, has about a zillion parameters, allowing you to set directory attributes—like Office, Organization and so on—without having to memorize the internal schema attribute names (I can never remember that “Last Name” is “sn” in the schema).

One neat thing about the commands is that they protect you from accidentally doing something stupid. For example, if you run Get-ADUser, you might expect to get a list of every user in the directory. In a large domain, that would not only take some time, but might well create a noticeable impact on your DC. To prevent that, the command’s –filter parameter is mandatory, forcing you to provide a starting point (such as an organizational unit) or some other criteria. Of course, the command won’t stop you from doing whatever it is you want to do; using –filter * will in fact retrieve every user from the directory. It will not, however, automatically retrieve every attribute of those users—because, again, that might drag a DC down for a bit. Additional parameters like –ResultPageSize, which lets you specify how many results to bring over at once, and –Properties, which lets you specify which attributes to retrieve, help you fine-tune the balance between performance and getting the information you need.

It’s Like You’re Hardly Working

I fondly—well, not really—recall the days when it took two dozen lines of VBScript to create and populate a new user in Active Directory. Now it’s as simple as:

PS AD:\> new-aduser -name DonJ -CannotChangePassword $True -Department IT -DisplayName 'Don Jones' -EmployeeNumber 42 -GivenName Don -Office 'Las Vegas' -Organization 'Concentrated Technology' -PasswordneverExpires $True

One neat trick: After you create a new user, you might want to do additional things with the user object. If you add the –PassThru switch to the command, the newly-created user object is output to the pipeline, where another cmdlet can accept it as input. That lets you do something like this:

New-ADUser ... -passThru | Set-ADAccountPassword ... -passThru | Enable-ADAccount

I’ve shortened the syntax, obviously—“...” is where all the normal parameters would go. This just illustrates how –passThru lets you continue outputting the user object to the pipeline so other cmdlets can do something with it. Techniques like this enable incredibly efficient one-liners—one command line, rather than a script—that let you work much more efficiently.

Wait … It Gets So Much Better

Here’s the spot where I set up a little shrine, right in my office, to the guys and gals who wrote these Active Directory commands: I discovered a little miracle called pipeline parameter binding, and these folks used it to full effect. Run Help New-ADUser –full, and start looking at the help for each individual parameter. You’ll notice that many of them—the ones that correspond to Active Directory attributes, like City and Office and Department—accept pipeline input “ByPropertyName.” What that means is you can pipe input into the New-ADUser cmdlet, and if your input contains properties that match the parameter name, then they’ll match automatically. So, if your input contains a “City” property, it’ll attach itself to the –City parameter. If your input has a “Department” property, it’ll hook itself up to the –Department parameter.

If you know how the Import-CSV cmdlet works, then you’re already excited. Imagine a .CSV file that contains columns like this:

"Name","Department","Organization","City"

Each line in the file then contains the information for those columns. You could easily create this structure in Microsoft Office Excel, Microsoft Office Access, Microsoft SQL Server, or whatever, and then export your data to CSV format. If you do that—remembering to match your column names to the parameter names of New-ADUser —then you can create new users like this:

Import-CSV c:\new-users.csv | New-ADUser

Yep, that’s all you’d have to type. Provided your .CSV file contains all the required columns—like Name, given the –Name parameter is mandatory—then New-ADUser will magically connect the right .CSV columns to the right parameters. You can import a hundred new users in seconds, by typing fewer than 50 characters. If that doesn’t completely sell you on learning Windows PowerShell 2.0 … well, I guess you must really like clicking “Next, Next, Finish.”

AD Management, Done Right

One of the basic tenets of Windows PowerShell is that programmers should write all of the administrative functionality—like managing Active Directory—in shell cmdlets. Any GUI should basically be a front-end to those cmdlets. Microsoft Exchange Server 2007 introduced this pattern to us, and it works great—you get a great GUI, and you always have the option of dropping to the command line if the GUI doesn’t do exactly what you need. So did Microsoft rewrite Active Directory Users and Computers this way?

Well, no. But honestly, that’s a pretty aged tool. However, another innovative feature in Windows Server 2008 R2 is the Active Directory Administration Center, an all-new GUI used for managing Active Directory. And guess what’s underneath the Administration Center? Yep, those Active Directory cmdlets. That means anything you do in the GUI, you can do from the shell—so anything that’s repetitive or boring, you can relegate to a shell script.

So, finally, after almost a decade, Active Directory has truly arrived. We now have the option of simple, intuitive management through a GUI, or more powerful, automated administration through a full-featured command line—that, frankly, isn’t that much more complicated than using the GUI. You don’t have to wait for Windows Server 2008 R2, because with the right add-on, your Windows Server 2003 domains can enjoy this same kind of manageability.

 

Don Jones is one of the nation’s most experienced Windows PowerShell trainers and writers. He blogs weekly Windows PowerShell tips at ConcentratedTech.com; you may also contact him or ask him questions there.