Print - Managing AD User Accounts with PowerShell

Active Directory (AD) is a vital part of the Windows enterprise infrastructure. Although Windows PowerShell scripting is available for Windows Server, PowerShell doesn’t include AD cmdlets. To address this need, you can download a free set of AD cmdlets (www.quest.com/
activeroles-server/arms.aspx) that let you easily perform basic user account operations. These cmdlets hide the complexities associated with using Active Directory Service Interfaces (ADSI). You can use the cmdlets with Active Directory Domain Services (AD DS) or Active Directory Lightweight Domain Services (AD LDS).

You can install the AD cmdlets on any computer running PowerShell. They can be used remotely with any AD domain controller (DC) in a network.

When you install the cmdlets, the ActiveRoles Management Shell for Active Directory shortcut is added to your Start menu. Clicking this shortcut starts a shell in which you can run the AD cmdlets as well as PowerShell’s default set of cmdlets. From this shell, you can easily perform such tasks as finding a user account, finding and reporting on groups of user accounts, modifying user properties, modifying user accounts, and creating user accounts.

Finding a User Account
Finding a user account isn’t easy in VBScript code. When you don’t know the user’s distinguished name (DN), you need to construct an LDAP query, which can take many lines of code. Not only are VBScript scripts for managing AD long, they require knowledge of LDAP queries, AD schema naming, and other technical details.

Finding a user is much easier with PowerShell.
If you want to use a logon name to find a user account, all you have to do is use the Get-QADUser cmdlet. For example, if you want to find the user account associated with the sAMAccountName dsotnikov, you’d type

Get-QADUser dsotnikov

Let’s look at what this cmdlet is doing. First, it establishes a connection with the current AD domain using the account under which you started the shell. If you want to connect to another domain, you can use the Get-QADUser cmdlet's -Service parameter or precede the statement with the Connect-QADService cmdlet. If you want to make the connection under different credentials, you can use the Get- QADUser cmdlet’s -Credential parameter or its -ConnectionAccount and -Connection Password parameters.

Because only the username is specified (dsotnikov), the Get-QADUser cmdlet assumes you want to use its default -Identity parameter to locate the account. (Specifying the name of the default parameter is optional in the AD and Power- Shell cmdlets.) The AD cmdlets provide a variety of ways to identify objects. Besides specifying a sAMAccountName (or domain\sAMAccountName), you can specify a display name, DN, user principal name (UPN), SID, or globally unique identifier (GUID), as in

Get-QADUser 'Dmitry Sotnikov'
Get-QADUser
  'cn=dsotnikov,ou=users,dc=quest,
  dc=com'Get-QADUser dsotnikov@quest.com
Get-QADUser S-123-4567…
Get-QADUser
  ABCD-1234-5677-98FE-CD43

(Column widths force us to wrap code. So, although the second command appears on two lines here, you would enter it on one line in the shell. The same holds true for the other multiline commands in this article.) Note that you need to enclose the parameter in quotes if it contains spaces (like in the display name example) or commas (like in the DN example). This is done to help the PowerShell parser understand that you’re passing in a single string.

Finding and Reporting on Groups of User Accounts
Systems administrators often need to find and report on groups of user accounts. The Get-QADUser cmdlet also handles this task. For example, if you want to see all the users in the accounting department, you’d use the -Department parameter, as in

Get-QADUser -Department Accounting

If you want to see all the users in the London office, you’d use the -City parameter, like this

Get-QADUser -City London

As these examples show, you can use the display names of the user attributes (e.g., Department, City), so knowing the attributes’ LDAP names is no longer required. However, you can use the LDAP names if you already know them. For example, if you want to use the LDAP name for the City attribute, you can run

Get-QADUser -L London

As Table 1 shows, Get-QADUser has many attribute-specific parameters you can use in searches. Plus, there are many other available parameters, such as -Identity, -Credential, -ConnectionAccount, and -ConnectionPassword. To get the full parameter list, type

Get-Help Get-QADUser -Full

Getting the information retrieved by Get- QADUser into a table, list, or .html file for easy viewing is simple. All you need to do is tell PowerShell how to format the results.

In both PowerShell and ActiveRoles Management Shell for Active Directory, the Get- cmdlets produce a collection of objects. To change the way in which these objects are presented, you need to direct, or pipe (|), the collection to another cmdlet. For example, if you want to present the information about the London users in a table, you’d pipe Get-QADUser’s results to PowerShell’s Format-Table cmdlet. To specify what attributes you want in the table and the order in which they appear, you use Format-Table’s -Property parameter. The -Property parameter is the default parameter, so specifying it in the command is optional. Thus, to present the London data in a table that includes the users’ names, departments, and titles, you’d type

Get-QADUser -City London |
  Format-Table Name,Department,Title

If you’d rather have the London data in a list, you can use PowerShell’s Format-List cmdlet, as in

Get-QADUser -City London |
  Format-List Name,Department,Title

For more information about how to use the Format-Table and Format-List cmdlets and what the results look like, see “PowerShell 101, Lesson 2,” March 2008, InstantDoc ID 97959.

If you want to convert and save the London data in an .html file, you can use PowerShell’s ConvertTo-HTML and Out- File cmdlets in the command

Get-QADUser -City London |
  ConvertTo-HTML
  -Property Name,Department,Title
  -Title 'London Staff' |
  Out-File C:\LondonUsers.html

Continue on Page 2

ConvertTo-HTML selects the properties specified with the -Property parameter (i.e., Name, Department, and Title), adds the title specified with -Title property (i.e., London Staff), and produces the corresponding HTML code. After the selected data is converted into HTML, it’s saved in the C: LondonUsers.html file with the Out-File cmdlet. For more information about the ConvertTo-HTML and Out-File cmdlets, see the PowerShell documentation.

Modifying User Properties
To modify user properties, you use the Set- QADUser cmdlet. You can use many of the attribute-specific attributes for Set-QADUser that you use for Get-QADUser (see Table 1). For example, to set Paris as the office location for a user, you’d use a command such as

Set-QADUser 'Dmitry Sotnikov'
  -City Paris

Bulk changes are just as easy. You can relocate everyone from the London office to the Paris office with the command

Get-QADUser -City London |
  Set-QADUser -City Paris

To reset a password, you use Set-QADUser’s -UserPassword parameter in a command such as

Set-QADUser 'Dmitry Sotnikov'
  -UserPassword '!@#Quh*$%'

Modifying User Accounts
There’s more to managing user accounts than just reporting on and setting their properties. Other common tasks include enabling, unlocking, moving, and deleting user accounts. To enable user accounts, you use the Enable-QADUser cmdlet. For example, the command

Get-QADUser -Disabled |
  Enable-QADUser

first uses Get-QADUser’s -Disabled parameter to find all the disabled accounts, after which it uses Enable-QADUser to enable them.

To unlock accounts, you use the Unlock- QADUser cmdlet. For example, the command

Get-QADUser -Locked -Title Manager |
  Unlock-QADUser

first uses Get-QADUser’s -Locked and -Title parameters to find the locked out accounts of users whose title is manager, then uses Unlock-QADUser to unlock those accounts.

To move user accounts, you use the Move-QADObject (and not Move-QADUser) cmdlet. Move-QADObject is a generic cmdlet that you can use to move any AD object to a different container. For example, to reorganize user accounts into organizational units (OUs) based on geography, you might use a command such as

Get-QADUser -City 'New York' |
  Move-QADObject NewParentContainer
  quest.com/staff/NewYork

This command begins by finding all the users in the New York office, then pipes the results to Move-QADObject, which moves them to the specified container. Note that the canonical name (quest.com/ staff/NewYork) is used to specify the target container. You could use a DN (e.g., cn= NewYork,ou=staff,dc=quest,dc=com) instead, but canonical names are much shorter and easier to type.

To delete user accounts, you use Remove- QADObject, a generic cmdlet that lets you delete any AD object. You simply specify the object to delete, as in

Remove-QADObject 'Unlucky One'

Although you’ll be given a warning message along with a prompt to confirm the delete action, it’s highly recommended that you use PowerShell’s -WhatIf parameter with Remove-QADObject first. When you use this parameter, PowerShell lists what objects will be deleted but doesn’t actually delete them. This is especially handy when you use pipelines for input and you’re not certain which accounts might get into the result set. For example, suppose you want to use Get- QADUser to retrieve any disabled accounts whose name starts with the letter a in the quest.com/recycled container and pipe the retrieved objects to Remove-QADObject for deletion. By using the -WhatIf parameter in the command

Get-QADUser -Name a* -Disabled
  -SearchRoot quest.com/recycled |
  Remove-QADObject -WhatIf

you’ll know exactly which objects will be deleted. Note that QADUser’s -SearchRoot parameter limits the scope to the specified container.

Continue on Page 3

Creating User Accounts
Many systems administrators would probably like an effortless way to create user accounts for newly hired employees. After all, who wants to repeatedly perform this routine task each time HR hires a new employee? To automate this task, you can use the New-QADUser cmdlet. For example, the command

New-QADUser -Name dsotnikov
  -ParentContainer quest.com/users
  -UserPassword 'P@ssw0rd'

creates a new user account named dsotnikov in the quest.com/users container. Although -Name and -ParentContainer are the only two mandatory parameters for the New-QADUser cmdlet, the account will be created disabled unless you also specify a password with New-QADUser’s -UserPassword parameter. Alternatively, you can set a password later by using the Set- QADUser cmdlet and enable the account with the Enable-QADUser cmdlet.

If you want to create a user account that has more attributes set, you can specify them in a New-QADUser command such as

New-QADUser -Name 'Dmitry Sotnikov'
  -ParentContainer quest.com/users
  -DisplayName 'Dmitry Sotnikov'
  -UserPassword 'P@ssw0rd'
  -sAMAccountName dsotnikov
  -FirstName Dmitry
  -LastName Sotnikov |
  Set-QADUser
  -UserMustChangePassword $true

At the end of this command, note how the new user object is piped to the Set-QADUser cmdlet and its -UserMustChangePassword parameter is set to $true ($true and $false are the Power- Shell way of expressing the corresponding Boolean values). This part of the command makes sure that the user is asked to reset the password at the first logon.

Now, typing all that information isn’t exactly quick and painless, especially if you need to create many user accounts. Fortunately, PowerShell comes with commaseparated value (CSV) file support. The Import-CSV cmdlet opens a CSV file and assumes the first row in the file has the names of the object properties that are listed in subsequent rows.

If the CSV file’s column names coincide with the names of the New-QADUser parameters, like in the following sample file

Name,sAMAccountName,UserPassword
First User,FUser,P@ssw0rd
Second User,SUser,P@ssword

you can simply pipe the CSV file’s contents to New-QADUser. You just need to use the

Import parameter, as in
  Import-CSV 'C:\provision.csv' |
  New-QADUser -Import
  -ParentContainer quest.com/users
  -City Columbus

As this example shows, you can add other parameters (in this case, -ParentContainer and -City) to the New-QADUser cmdlet.

With this setup, you can tell HR to put the information about new employees in a CSV file in an agreed-on location and you can schedule a command like the one just given to run daily. Because you won’t have to manually create those accounts anymore, you’ll have more time for other administrative tasks.

If you want to try the New-QADUser cmdlet in a test environment, you can use the command

1..500 | ForEach-Object {
  New-QADUser
  -ParentContainer quest.test/test
  -Name "testuser$_"
  -SamAccountName "testuser$_"
  -UserPrincipalName
  "testuser$_@example.com"
  -FirstName "testUser$_"
  -LastName "example$_"
  -UserPassword "P@ssword@_$_"
}

to quickly create 500 test user accounts with unique attributes. This code uses Power- Shell’s range operator (..) to get a collection of 500 numbers (1 through 500). The collection is piped to the ForEach-Object cmdlet, which cycles though the collection, putting each number inside the various parameters’ string values so that, for example, testuser$_ becomes testuser1 in the first loop, testuser2 in the second loop, testuser3 in the third loop, and so on. Note the use of the double quotes around the string values. The double quotes tell PowerShell to automatically evaluate the $_ variable inside the strings. (If you’re unfamiliar with the $_ variable, see “PowerShell 101, Lesson 2.") Using single quotes won’t work.

Easily Manage User Accounts and a Lot More
As you can see, ActiveRoles Management Shell for Active Directory contains many cmdlets that you can use to manage user accounts. It also contains many more cmdlets. Version 1.1 has 40 cmdlets for managing not only users but also groups, group memberships, computers, permissions, Windows Server 2008 fine-grained password policies, and more. To see the full list of cmdlets and what they do, you can download the “ActiveRoles Management Shell for Active Directory - Administrator’s Guide” from www.quest.com/powershell/activerolesserver. aspx or visit the online reference at wiki.powergui.org/index.php/QAD_ cmdlets_reference.

When I try to use the New-QADUser command I receive a constraint error. Does anyone know why?

Wi!!y, It is hard to tell what exactly is happening in your environment based on the information you posted. What I would recommend you do is go to the Active Directory and PowerShell discussion forum at http://powergui.org/forum.jspa?forumID=173 and post the exact command you are using and the error you are getting there. Dmitry