Meet Set-ADUser, an All-Purpose Hammer

In “3 PowerShell Account Tweaks,” I continued my discussion of Active Directory (AD) “hammers”—PowerShell cmdlets that don't just find users who meet particular criteria (what I've called the “filters”) but also accomplish something, such as unlocking an account. Thus far, I’ve shown you disable-adaccount, enable-adaccount, unlock-adaccount, and clear-ADAccountExpiration. Those are very useful, specifically focused tools, but this month I want to introduce you to the ultimate tool for AD account tweaking: set-aduser.

Set-aduser basically looks like
 

set-aduser -identity IDinfo -changeparameters

where IDinfo is—like the -identity parameter we used with get-aduser—either an object's samaccountname, distinguished name (DN), object GUID, or SID. The -changeparameters option refers generically to a whole pile of parameters that can change dozens of AD attributes such as title, description, and so on. For example, to change the display name of an account with the samaccountname JulesM to Julie Marsella, you'd type
 

set-aduser julesm -displayname "Julie Marsella"

The AD PowerShell folks included a lot of attribute-specific parameters, like -Company, -Givenname, -description, and others, so you'll probably find that set-aduser already has a built-in parameter that matches what you want to change. Most of them take simple strings, so you can change a bunch of attributes all in one shot, as in
 

set-aduser MartinT -description "Debugger" -Initials "R" -surname "Thomas"

As is often the case, the AD PowerShell team has made our lives a bit easier in a few ways. For example, specifying an account's Manager value requires a complete DN in most tools, but that's not the case here. Thus, if JulesM were MartinT's manager, then the command
 

set-aduser MartinT -manager JulesM

would let you tell that to AD (rather than -manager "cn=julesm,cn=users,dc=bigfirm,dc=com" or something like that).

Similarly, you might know that the AD attribute name for someone's last name is sn, which you probably know is a shortening of surname. That has always seemed odd to me because the AD attribute for what Americans would call a first name is givenname and it's completely spelled out, so why is the last name attribute sn rather than surname? The AD PowerShell folks have, however, made our lives easier by creating a sort of "synthetic" attribute called surname rather than sn. That does make changing someone's last name a bit odd if you're AD-savvy, because typing

set-aduser MartinT -sn "Thomas"

will get you an error, whereas
 

set-aduser MartinT -surname "Thomas"

works just fine. And that's not the only case of a "synthetic" attribute. You might recall that LastLogonDate is a godsend if you’re trying to figure out who hasn't logged on in a while. The AD space for an email account is called mail inside AD, but you need to use -emailaddress rather than -mail to change an account's email address.

That, however, brings up an important point: What about custom AD attributes? How can I set a value of an AD attribute that some third-party application added to AD—like, say, shoesize? In cases like that, you can use the -replace parameter. You can change any arbitrary AD attribute or attributes with the following syntax:

set-aduser identifier -replace @{attributename="newvalue";"attributename="newvalue" . . .}

For example, to set Martin's userprincipalname and givenname, you'd type
 

set-aduser MartinT -replace @{userprincipalname="[email protected]";givenname="martin"}

Note that when using -replace, the attribute names must match their internal AD values (indicating that there's almost certainly some LDAP queries lying just below the surface), so to set Martin's email address and manager, you'd have to type the internal AD attribute name (mail) and specify the manager's name as a DN, as in
 

set-aduser MartinT -replace @{mail="[email protected]";manager="cn=julesm,cn=users,dc=bigfirm,dc=com}

Set-aduser lets you clear any existing value with -clear, as in
 

set-aduser MartinT -clear mail

And again, -clear needs the internal LDAP names of the AD attributes. Some AD attributes allow more than one value, as is the case with othermobile, and can be set with -add, as in
 

set-aduser martint -add @{othermobile="+1724333-5544"}

You could then add as many more phone numbers as you want, and AD will store them for you. You can then see them with the get-aduser command, as in
 

get-aduser martint -pr othermobile | select othermobile

Rounding out the set of commands begun with -replace, -clear, and -add, there's -remove, which removes an item from a list. To remove that first phone number from Martin's othermobile list, you’d use
 

set-aduser martint -remove @{othermobile="+1724333-5545"}

And in case you're wondering, set-aduser doesn't try to parse phone numbers to see if they make sense. Set-aduser gives you a finely tuned ability to modify AD attributes. We'll see more of that next month!