Are you tired of opening up Active Directory (AD) Users and Computers (ADUC), clicking around, making typos and going through the motions of creating a new user account for the sixth time today? If so, you need to automate this ever-so-common process with PowerShell using the New-AdUser cmdlet!

It's Friday evening and one hour before you are planning to go home for the weekend. It's been a busy week, so you've decided to make plans to watch the big game with your closest friends. But, your boss casually walks over and asks, "Did you get the email? Can you handle this by the end of the day?" You quickly open Microsoft Outlook and sure enough it's an email from the HR department, with you cc'd by your manager, asking you to provision 400 new employee Active Directory (AD) accounts before you leave the office. Great. There goes the game.

You quickly search the Internet for some options to expedite creating these user accounts and discover that you can automate the AD account provisioning using a PowerShell cmdlet called New-ADUser.

Typically, admins manually create AD accounts by using the AD Users and Computers MMC snap-in installed on your desktop computer installed via Remote Server Administration Tools (RSAT). But creating an AD user this way takes, on average, three minutes per user account. Creating AD user accounts isn't a glamorous job and is ripe for automation.

There are three common ways admins create AD user objects using the New-AdUser cmdlet.

  1. Create a single AD user account using the required and additional cmdlet parameters.
  2. Copy an existing AD user object to create a new account using the Instance parameter.
  3. Pair the Import-Csv cmdlet with the New-ADUser **cmdlet to create multiple Active Directory user objects using a comma-separated value (CSV) file.

These practices can sometimes be combined to together to create a more efficient solution. For example, you can use all three options to create a template AD account that can be copied using a CSV file to generate multiple new AD accounts.

In this article, you're going to learn how to use New-AdUser  taking advantage of each of these methods.

Prerequisites/Requirements

Before you get started using the New-AdUser cmdlet, you'll first need to ensure you meet a few prerequisites.

  • Windows PowerShell 5.1
  • The Remote Server Administration Tools (RSAT) package installed. This package installs the Active Directory PowerShell module which contains the New-AdUser cmdlet
  • Logged onto a Windows computer in the same domain as the user accounts you'd like to create
  • Logged in as an AD user account with permission to create new user accounts

Once you meet these requirements, you're good to go!

Creating a Single User Account

Let's first create a single user account to demonstrate how New-ADUser works at a basic level. You'll find that New-ADUser doesn't have many mandatory parameters. In fact, the only mandatory parameter is the Name parameter but is seldom used alone.

You'll usually use many different parameters to create an user account. Luckily, most of the parameters are self-explanatory and match up well with what you see in ADUC. You can see in the example below, you can easily use a lot of parameters. Each parameter roughly correlates to a single user account attribute.

Note that we're using backticks in the example. This is only to prevent a long single line for readability purposes.

PS51> New-ADUser `
    -Name "Kevin Sapp" `
    -GivenName "Kevin" `
    -Surname "Sapp" `
    -SamAccountName "kesapp-test" `
    -AccountPassword (Read-Host -AsSecureString "Input User Password") `
    -ChangePasswordAtLogon $True `
    -Company "Code Duet" `
    -Title "CEO" `
    -State "California" `
    -City "San Francisco" `
    -Description "Test Account Creation" `
    -EmployeeNumber "45" `
    -Department "Engineering" `
    -DisplayName "Kevin Sapp (Test)" `
    -Country "us" `
    -PostalCode "940001" `
    -Enabled $True
The organizational unit (OU) where the AD user object is contained cannot have a duplicate SamAccountName.

Now that the account is created, confirm the account was created using the Get-ADUser cmdlet. Below you can see that Get-AdUser returns some common attributes for the user account just created.

PS51> Get-ADUser -Identity kesapp-test -Properties State,Department,Country,City

DistinguishedName : CN=Kevin Sapp,CN=Users,DC=mylab,DC=local
Enabled           : True
GivenName         : Kevin
Name              : Kevin Sapp
ObjectClass       : user
ObjectGUID        : 3b18338d-b3c7-4d00-a54a-1d3121e1363f
SamAccountName    : kesapp-test
SID               : S-1-5-21-1181311581-1397355964-1468337501-1109
Surname           : Sapp
UserPrincipalName : [email protected]

Copying an Existing AD User Object

Another method to account creation is to copy an existing AD user object and use it as a template for a new AD account. There are several benefits to this approach:

  • It saves the time of having to specify each parameter individually
  • It helps to standardize AD account creation
  • It prevents human error caused by manual account creation and allows for employees on the same team to have the same custom AD attributes

For this example, you'll use the account just created as a template (kesapp-test). Perhaps you need to create a new user account with the same state, location, department, country, and city AD attributes. This new account will be for the employee James Brown.

Note that there is a limitation with this approach and only the following AD account properties listed in the link below are able to be copied with this process. For more information, check out the Copy a User's Properties Microsoft docs page.

The first step is to find the AD user account that will be used as a template along ensuring all of the attributes to copy are provided via the Properties parameter. To do that, use the Get-ADUser cmdlet as shown below. This simply stores the AD user object in the $template_account variable.

Note that the second line is setting the template object's UserPrincipalName (UPN) property to $null. This is recommended to ensure the template's UPN is unique. Each AD user account must have a unique UPN.

$template_account = Get-ADUser -Identity kesapp-test -Properties State,Department,Country,City
$template_account.UserPrincipalName = $null

Once you have the template user account captured, you can use that object as a value for the Instance parameter and provide any user-specific parameters to fill in the other attributes as shown below.

New-ADUser `
    -Instance $template_account `
    -Name 'James Brown' `
    -SamAccountName 'jbrown' `
    -AccountPassword (Read-Host -AsSecureString "Input User Password") `
    -Enabled $True

You should now have an account for James with all of the allowed AD attributes brought over by the template object.

User Account Template Gotchas

One common mistake with this approach is to use the * wild card for the Properties parameter when capturing the template object. Admins do this because they want to copy copy all of the user account properties at once. But this doesn't work.

For example, the command below will throw an error:

$template_account = Get-ADUser -Identity kesapp-test -Properties *
New-ADUser `
    -Instance $template_account `
    -Name 'James Brown' `
    -SamAccountName 'jbrown' `
    -UserPrincipalName '[email protected]' `
    -AccountPassword (Read-Host -AsSecureString "Input User Password") `
    -Enabled $True

The problem with this approach is that the UserPrincipalName attribute needs to be unique across the AD Forest. Therefore, the UPN should be overwritten in the New-ADUser command or set to null in the template variable (shown below).

$template_account.UserPrincipalName = $null

Another reason that using the wildcard approach fails is that some of the AD properties being copied over by the wildcard are read-only (owned by the Security Account Manager).

Creating New User Accounts with a CSV File

Taking what you've learned a step further is to read employee accounts from a CSV file and use New-ADUser to create AD user accounts.

This solution is often used by many organizations to automate account creation in conjunction with HR systems that create flat files new employee onboarding information.

Let’s say that you've been sent a list of new employees in a CSV file. Each row in the CSV file represents a single row and has the following columns: FirstName, LastName, Department, State, EmployeeID, and Office. The naming convention for the user login account is the employee's first initial concatenated with the last name such as ksapp for the employee Kevin Sapp.

FirstName, LastName, Department, State, EmployeeID, Office, UserPrincipalName, SamAccountName, Password
Micheal, Jordan, NBA, Chicago, 23, Chicago Bulls, [[email protected]](<mailto:[email protected]>), mjordan, [email protected]
Lebron, James, NBA, Los Angeles,24, LA Lakers,[[email protected]](<mailto:[email protected]>), ljames, [email protected]
Dwayne, Wade, NBA, Miami, 13, Miami Heat, [[email protected]](<mailto:[email protected]>), dwade, [email protected]

$import_users = Import-Csv -Path sample.csv
CSV File saved as sample.csv

Once you have the CSV file, then use Import-Csv to read the CSV file and capture each row as a single object. Then iterate over each of those rows passing the appropriate fields in the CSV file to the expected parameters of New-ADUser. You can see an example of this below.

$import_users | ForEach-Object {
    New-ADUser `
        -Name $($_.FirstName + " " + $_.LastName) `
        -GivenName $_.FirstName `
        -Surname $_.LastName `
        -Department $_.Department `
        -State $_.State `
        -EmployeeID $_.EmployeeID `
        -DisplayName $($_.FirstName + " " + $_.LastName) `
        -Office $_.Office `
        -UserPrincipalName $_.UserPrincipalName `
        -SamAccountName $_.SamAccountName `
        -AccountPassword $(ConvertTo-SecureString $_.Password -AsPlainText -Force) `
        -Enabled $True
}

Summary

In this post, you learned how to provision new user accounts using three different methods:

  1. Single account creation
  2. Copying a user account from a template
  3. Creating multiple accounts using a CSV file

These are basic ways to provision new users in your environment. These methods work great when you bundle them together by creating a PowerShell function and module. You can even take things a step further and create your own automation process using a SQL or Oracle database as the source (instead of a CSV file).  Feel free to leverage each method based on your own unique requirements and use cases.

Hopefully, this information will save you in a pinch! You learned a new skill and were able to make it to the party with your friends without sacrificing your work-life balance!

Further Reading