Creating an AD Sync PowerShell Tool with a CSV File

Adam Bertram

Adam Bertram

Read more posts by this author.

Learn how to use a community PowerShell module called PSADSync to sync AD with PowerShell (users). We will cover how to set up a simple AD sync with a CSV file in this tutorial blog post.

One of the most common requests I get to automate is syncing employee user information in a CSV into Active Directory. Lots of organizations have some kind of HR database that contains information about all employees. They also have Active Directory where each employee has a user account but they have no automated way to get the employees from HR into Active Directory.

This is where PowerShell can come in.

PowerShell can do everything you need. It can:

  • read CSV files (or even databases)
  • collect all the necessary attributes
  • either find a matching user in Active Directory
  • populate the necessary user attributes or even create a new one

It all depends on how your PowerShell tool is built.

Setting Up

Because this is such a common request, I’ve built a PowerShell module called PSADSync that you can download right now from the PowerShell Gallery. Simply type Install-Module -Name PSADSync to download and install it onto your computer.

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.

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.


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 the 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, first ensure the AD users 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
---------- --------- -------

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


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!

Subscribe to Adam the Automator

Get the latest posts delivered right to your inbox

Looks like you're offline!