Creating bulk Active Directory user and group accounts in PowerShell using Server 2008 R2 cmdlets

This one is a departure from my normal SharePoint-related articles. Back in the day, I maintained a few batch and VBS scripts that created multiple Active Directory users and groups from CSV files. These had obvious uses for creating test accounts on a development environment, but I also used them from time to time on customer production environments when it came to provisioning new user accounts on mass.

One of the new features introduced in Windows Server 2008 R2 was the inclusion of 76 cmdlets delivering extensive Active Directory management capabilities using PowerShell. The challenge was to upgrade my old batch files to PowerShell versions using these new cmdlets, building in the following features:

Create bulk user accounts from a CSV file, including specifying attributes and account options (e.g., change password at next logon)

Create bulk group accounts from a CSV file, specifying a description and group type (e.g., global, security)

Assign multiple users to groups as members using a CSV file

Exception handling so that the script would check first to see if the account or group member existed before attempting to make the change

To achieve this, I have created three PowerShell functions – one to create users, one to create groups, and a final one to read the CSV file, kick off one of the other two functions depending on the type of account to be created, and finally add users as group members. Once these functions are loaded in a PowerShell console, it only requires a single command to create either users or groups – along with an appropriate CSV file, of course.

Rather than go through each stage of these functions in this article, I have instead decided to annotate the script at various points so that you see what is happening. To get the functions ready for use, save them into a PS1 file using notepad or your favourite script editor and load it from a PowerShell console on a Windows Server 2008 R2 domain controller.

#Import the PowerShell module containing AD cmdlets
Import-Module ActiveDirectory
   
#Read a CSV file with the user or group details and create an account in AD for each entry
Function Create-ADAccountsFromCSV {
    Param (
        [parameter(Mandatory=$true)][string]$CSVPath,
        [parameter(Mandatory=$true)][string]$Type,
        [parameter(Mandatory=$true)][string]$OrgUnit
        )
 
    if (($Type -ne "Group") -and ($Type -ne "User"))
    {
        Throw New-Object System.ArgumentException("Type parameter must be specified as either 'User' or 'Group'.")
    }
 
    #Read the CSV file
    $csvData = Import-CSV $CSVPath
    foreach ($line in $csvData) {
       
        #Create a hash table of the account details
        $accountTable = @{
            'givenName'=$line.FirstName
            'sn'= $line.LastName
            'displayName'= $line.DisplayName
            'sAMAccountName'= $line.sAMAccountName
            'password' = $line.Password
            'description' = $line.Description
            'ou' = $OrgUnit 
        }
               
        if ($Type -eq "User")
        {
            #Call the function to create a user account
            CreateUser -AccountInfo $accountTable
        }
 
        if ($Type -eq "Group")
        {
            #Call the function to create a group account
            CreateGroup -AccountInfo $accountTable
           
            #Get new group
            $groupFilterString = "samAccountName -like `"" + $line.sAMAccountName + "`""
            $group = Get-ADGroup -Filter $groupFilterString
           
            #Walk through each member column associated with this group
            $memberColumnNumber = 1
            $memberColumn = "Member" + $memberColumnNumber
           
            #While a member column still exists, add the value to a group
            while ($line.$memberColumn)
            {
                #Check if user is already a member of the group
                $member = Get-ADGroupMember $group | where { $_.samAccountName -eq $line.$memberColumn }
               
                #If not already a member, add user to the group
                if ($member -eq $null)
                {
                    write-host "Adding" $line.$memberColumn "as a member to group" $group.Name
                    try
                    {
                        $userFilterString = "samAccountName -like `"" + $line.$memberColumn + "`""
                        $user = Get-ADUser -Filter $userFilterString
                        Add-ADGroupMember -Identity $group -Members $user
                    }
                    catch
                    {
                        write-host "There was a problem adding" $line.$memberColumn "as a member to group" $group.Name "-" $_ -ForegroundColor red
                    }
                }
                else
                {
                    write-host "User" $line.$memberColumn "not added to group" $group.Name "as it is already a member" -ForegroundColor blue
                }
               
                $memberColumnNumber = $memberColumnNumber + 1
                $memberColumn = "Member" + $memberColumnNumber
            }
        }
    }
}        

#Create an Active Directory user
Function CreateUser {
  Param($AccountInfo)
 
    try
    {
        #Check to see if the user already exists
        $userFilterString = "samAccountName -like `"" + $AccountInfo['sAMAccountName'] + "`""
        $user = Get-ADUser -Filter $userFilterString
       
        #If user not already created, create them
        if ($user -eq $null)
        {
            write-host "Creating user account:" $AccountInfo['sAMAccountName']
           
            #Create the user account object
            New-ADUser -SamAccountName $AccountInfo['sAMAccountName'] `
                       -Name $AccountInfo['displayName'] `
                       -DisplayName $AccountInfo['displayName'] `
                       -GivenName $AccountInfo['givenName'] `
                       -Surname $AccountInfo['sn'] `
                       -Path $AccountInfo['ou'] `
                       -ChangePasswordAtLogon $true `
                       -AccountPassword (ConvertTo-SecureString $AccountInfo['password'] -AsPlainText -Force) `
                       -Description $AccountInfo['description'] `
                       -Enabled $false
       
            #Set 'User must change password at next logon' to true after user has been created
            #For some reason, the option wasn't set during New-ADUser - could be a bug?
            $user = Get-ADUser -Filter $userFilterString
            Set-ADUser $user -ChangePasswordAtLogon $true          
        }
        else
        {
            write-host "User" $AccountInfo['sAMAccountName'] "not created as it already exists" -ForegroundColor blue
        }
    }
    catch
    {
        write-host "There was a problem creating the user" $AccountInfo['sAMAccountName'] "-" $_ -ForegroundColor red
    }
}

#Create an Active Directory group
Function CreateGroup {
    Param($AccountInfo)
 
    try
    {
        #Check to see if the group already exists
        $groupFilterString = "samAccountName -like `"" + $AccountInfo['sAMAccountName'] + "`""
        $group = Get-ADGroup -Filter $groupFilterString
       
        if ($group -eq $null)
        {  
            write-host "Creating group account:" $AccountInfo['sAMAccountName']
           
            #Create the group account object
            New-ADGroup -SamAccountName $AccountInfo['sAMAccountName'] `
                        -Name $AccountInfo['sAMAccountName'] `
                        -Path $AccountInfo['ou'] `
                        -GroupScope Global `
                        -GroupCategory Security
        }
        else
        {
            write-host "Group" $AccountInfo['sAMAccountName'] "not created as it already exists" -ForegroundColor blue
        }
    }
    catch
    {
        write-host "There was a problem creating the group" $AccountInfo['sAMAccountName'] "-" $_ -ForegroundColor red
    }  
}

Creating users

Once the functions have been loaded in a PowerShell console, you are ready to start creating user accounts from a CSV file. The header of the CSV file for this example should be, as follows:

sAMAccountName,FirstName,LastName,DisplayName,Description,Password

Something to note is that I have used a very limited number of attributes when creating a user account – for example, I haven’t specified an Office, Department, Phone Number, Address, etc. You can extend the script to include these by adding extra columns to the CSV file and adapting the CreateUser function in the script, using the appropriate parameters for the New-ADUser cmdlet, as specified on TechNet here.

Once you have these columns populated with user accounts, save the CSV file to a local or network path. For this example, I am going to copy the file into C:\Scripts and call it UserAccounts.csv.

You now need to decide which Organisational Unit (OU) to store the users in Active Directory. I could have added this information to an extra column in the CSV file and made a slight modification to the script, but I decided to use a single OU in the PowerShell command instead. You can always move them to a different OU afterwards using the Active Directory Users and Computers console, if required.

To create my users in the OU “Staff” for the domain “acme.local”, I would need to use the following command:

Create-ADAccountsFromCSV -CSVPath "C:\Scripts\UserAccounts.csv" -OrgUnit "OU=Staff,DC=acme,DC=local” -Type "User"

The script will output operation progress to the console, including a warning when it discovers that an account already exists and will not attempt to create it.

Creating groups and assigning members

The CSV file for adding groups should have the following header:

sAMAccountName,Member1,Member2,Member3,Member4,Member5

The first column should contain the group name, followed by a column for each group member. Note that although I have only included Member 1 to 5 in the example above, you can have as many members as you like by creating extra columns in the header for Member6, Member7, etc.

As with adding users. there are also extra parameters available for the New-ADGroup cmdlet, as specified on TechNet here.

Once you have the CSV file formatted with the correct groups and their members, save it to a local or network path for use with the script. For this example, I am going to copy the file into C:\Scripts and call it GroupAccounts.csv. To create my groups in the OU “Groups” for the domain “acme.local”, I would need to use the following command:

Create-ADAccountsFromCSV -CSVPath "C:\Scripts\GroupAccounts.csv" -OrgUnit "OU=Groups,DC=acme,DC=local” -Type "Group"

As with creating users, the script will output progress to the PowerShell console, including warnings when either a group already exists or a user is already a member of the group - in both cases it will ignore these operations and move on without making a change.