Import Users in Active Directory with PSADSync

If you need to import users in an Active Directory domain, you’ve come to the right blog post. No more using Active Directory Users and Computers. In this post, you’re going to use how to use PowerShell to read a CSV file and not only create users but also sync AD attributes with user accounts in the CSV file.

If you look around the web, you’ll find countless PowerShell scripts and snippets to import users into Active Directory. You’ll either find expensive commercial tools or dinky scripts. To prevent this, I’ve built a PowerShell module called PSADSync.

The PSADSync PowerShell module takes care:

• reading CSV files (or even databases)
• collecting all the necessary attributes
• finding a matching user in Active Directory
• populating the necessary user attributes or even creating a new one

Setting Up

To set things up, open up your PowerShell console and install the PSADSync module.

Install-Module PSADSync

The only requirements are that PowerShell v4 is installed, you have rights in Active Directory to make attribute changes to user accounts and the computer that the tool will be running on is a member of Active Directory.

The module uses the ActiveDirectory module but it will download and install it for you if you don’t have it already.

Related: How to Install the PowerShell Active Directory Module

Once you’ve got the module installed, it’s time to gather up that CSV file full of employee information you’d like to sync to Active Directory.

Below is the CSV file I’ll be working with. It has three employees in it represented by their first name, last name and their internal employee ID from some HR source.

FirstName,LastName,EmployeeNumber
Adam,Jones,1
Bob,Baker,2
Sherry,Risley,3

I’d like each employee in this CSV file to have the exact same first and last name represented in AD. This is one of the first steps in our AD sync PowerShell tool.

But first, I need to find a match between a CSV row and a single AD user account. To make this match, I’ll need a unique identifier. For this instance, I have an employee number. In AD, this is represented by the EmployeeId field. The tool will use this to make a 1:1 match.

I define this matching by mapping the CSV EmployeeNumber field to the AD EmployeeId attribute using a PowerShell hashtable.

$fieldMatchMap = @{ EmployeeNumber = 'EmployeeId' }

Next, I need to map each of the CSV fields with the an AD field to tell the tool which CSV fields match up to which AD attributes. I’ll do this again by creating another hashtable.

Notice that the key value in the hashtable is the CSV field and the value for each key/value pair is the AD attribute to check and change, if necessary.

$fieldSyncMap = @{
    FirstName = 'givenName'
    LastName = 'sn'
}

Now that we have everything mapped correctly, you’re one step closer to importing users in Active Directory! Now ensure the AD user objects are different than what they are supposed to be.

You can see below that none of them have a GivenName or a Surname attribute. When we’re done, these accounts should match what’s in the CSV fields.

PS> 1,2,3 | foreach { Get-AdUser -Properties EmployeeId -Filter "EmployeeId -eq $_" } | select employeeId,givenname,surname

employeeId givenname surname
---------- --------- -------
1
2
3

Running the AD Sync PowerShell Tool

Now run the tool. Running PSADsync is done using the Invoke-AdSync command. I’ll use the hashtables I just built to pass to Invoke-AdSync as well as specifying the location of the CSV file I’ll be using.

PS> $fieldMatchMap = @{ EmployeeNumber = 'EmployeeId' }
PS> $fieldSyncMap = @{
        FirstName = 'givenName'
        LastName = 'sn'
    }
PS> Invoke-AdSync -FieldSyncMap $fieldSyncMap -FieldMatchMap $fieldMatchMap -CsvFilePath 'C:\Employees.csv'

Now we’ll do another check to ensure all of the attributes have been populated.

PS> 1,2,3 | foreach { Get-AdUser -Properties EmployeeId -Filter "EmployeeId -eq $_" } | select employeeId,givenname,surname

employeeId givenname surname
---------- --------- -------
1          Adam      Jones
2          Bob       Baker
3          Sherry    Risley

Summary

This was just an intro to syncing AD with PowerShell. The PSADSync module supports many different scenarios and has an extensive suite of Pester tests. It should be able to support just about whatever kind of syncing you’d like to do!