On-boarding New Users with PowerShell

​On-boarding new employees can be one of the most repetitive tasks that IT personnel have to do. Think about it; there are so many steps and variables that it’s easy to miss steps. A checklist can help ensure steps aren't missed, but I find that using pre-written PowerShell scripts will deliver the same consistent results every time. Here are some of the steps we will be scripting in this article:​

• Create the domain user account
• Add user to security groups
• Add user to distribution groups
• Create an Exchange mailbox​
• Configure the user's attributes:
  • Gender
  • Job Title
  • Department
  • Location
• Create a Home directory
• Create an Application directory
• Issue a security badge (if your application accepts command line input)
• Create logs showing the steps performed​​

Click below to view the full .ps1 on github

NewUser.ps1

Note: Be sure to take your environment and requirements into consideration when running scripts. Be careful defining your variables.

Create the User: 
In Active Directory I find that it's easier to copy an exisiting user who is considered a peer and already has the same security groups that the new user will need. Before creating (or copying) a user, it is necessary to know which Organizational Unit the user needs to be placed into in Active Directory so that the correct Group Policies apply to that user. We'll accomplish this by finding out all of these variables BEFORE creating the user. Here's a sneak peek:

#Get Department and verify correct spelling *************************************
Function Get-Department {
     $Global:Department = Read-Host "Please Choose a Department"
     if ($Department -eq $null){
          Write-Host "Department cannot be blank. Please re-enter department."
          Get-Department
     }
     $DeptCheck = $Departments -contains "$Department"
     if ($DeptCheck -eq $False){
          Write-Host "_____________________________________________________________"
          Write-Host "'$Department' is not a department. Please re-enter department."
          Get-Department}
}
Get-Department

Groups:
If you copy an existing user, the new user will inherit the original user's group membership by default. This includes security groups and dsitribution groups. Depending on your environment, you may not want this behvior. For today's article we will be assuming that it is ok to copy existing users to make new users. Be sure when making this decision that you take into consideration the 'least priviledge' principle for security measures.

Pro tip: Role-based access is always preferred over user-based access. Be sure to configure appropriate security groups and use them throughout your environment to grant access to network shares, applications,  websites, etc. For more details, see my article called Security Groups: Sweet Dreams or Worst Nightmare?

Additionally some users need to be assigned groups based on location, department, gender, etc. That can be accomplished with variables and 'if' statements. Here's an example in PowerShell of how you could assign the user a group based on their gender:

#Assign distribution group based on gender *************************************
$Male = "m", "M"
$Female = "f", "F"
$DName = Get-ADUser -Identity "$Username" | Select-Object -ExpandProperty DistinguishedName
$LDAPUser = [ADSI]"LDAP://$DName"
Function Assign-Group {
     if ($Male.contains($Gender) -eq $True){
          $MenMember = $MenGroup.IsMember($LDAPUser.ADsPath)
          if ($MenMember -eq $False){
               Add-ADGroupMember -Identity "Men" -Members $Username -ErrorVariable $Err1 -                      ErrorAction "SilentlyContinue" -Confirm:$false
               Write-Host "Added $Username to distribution group for Men"
          }
     else {
          Write-Host "$Username is already a member of distribution group for Men"
     }
     }
     elseif ($Female.contains($Gender) -eq $True){
          $WomenMember = $WomenGroup.IsMember($LDAPUser.ADsPath)
          if ($WomenMember -eq $False){
               Add-ADGroupMember -Identity "Women" -Members $Username -ErrorVariable $Err2                     -ErrorAction "SilentlyContinue" -Confirm:$false
               Write-Host "Added $Username to distribution group for Women"
          }
          else {
               Write-Host "$Username is already a member of distribution group for Women"
          }
     }
     else {
          Write-Host "Something with the gender variable went wrong..."
     }
Assign-Group
}

Email: 
Users must be provisioned an email address in the right format in accordance with your organization's standards. Different organizations use different syntax for their user's emails. Examples for John Smith include jsmith@domain.com, john.smith@domain.com, johns@domain.com, john@domain.com, etc. These email addresses don't even factor in distribution groups or additional aliases such as sales@domain.com or manager@domain.com. Another consideration; should this user have Active Sync / IMAP enabled so they can access their email on a mobile device?

# Define the email to be used in Active Directory
$Email = "$FirstName.$LastName@domain.com"
​
#Determine the Exchange storage group with most free space ************************
$UserCan = (Get-ADUser -Identity $Username -Server $Server -Property CanonicalName).CanonicalName
$edbGUID = (Get-MailboxDatabase -server $Exchange | Sort-Object length | Select -First 1).guid
$UserGUID = (Get-ADUser -Identity $Username -Server $Server).ObjectGUID
$UserDN = (Get-ADUser -Identity $Username -Server $Server).distinguishedname

#Create mailbox ***************************************************************
Enable-Mailbox -DomainController $Server -Identity "$UserCan" -Alias "$Username" -Database "$edbGUID" -ManagedFolderMailboxPolicy "Mailbox Cleanup"

Home Directory: 
Most environnts place all user folders in the same root direct for “easy” management. I put “easy” in quotes because this can become a permissions nightmare if it’s not set up properly from the start and maintained properly, by every admin, forever. In this environment we have created an NTFS folder that has all of the default permissions we want. The script creates a new folder, pulls the permissions of the template folder, assigns those same permissions to the new folder, and then grants the user access to the new folder. The result; every folder has the same default permissions plus Modify access for the user the folder belongs to.

Pro tip: Don’t let users take ownership of their folders or change the permissions. You’ll just be in for a challenge when the time comes to archive their folder at termination. That’s why we remove that ability from the start. ​

#User's home folder where they will store personal files
$HomePath = "\\HomeFolderPath\Users"

# Remember we use the switch below when we created the user, so that Active Directory
# would know where to find this user's folder: -HomeDirectory "$HomePath\$Username"

#Create user's home drive and set permissions ********************************
New-Item -ItemType directory -Path "$HomePath\$Username" | Out-Null
# You must create a template folder with the default permissions you want at this location $HomePath\template-DoNotDeleteOrMove"
$ACLp = (Get-Item "$HomePath\template-DoNotDeleteOrMove").GetAccessControl('Access')
$ARpe = New-Object System.Security.AccessControl.FileSystemAccessRule("$Username","Modify","ContainerInherit,ObjectInherit","None","Allow")
$ACLp.AddAccessRule($ARpe)
Set-ACL -Path "$HomePath\$Username" -ACLObject $ACLp
$HomeDrive = "$HomePath\$Username"

# We also reference the Home Folder later in the script when we place a shortcut inside of it that leads to a Department-specific network share

​Application Directory: 
Some organizations have applications that require each user be created a directory for a specific application. Creating that directory in the right place, with the right name, and the right permissions can leave room for human error. Just like the home folder above  we create a new folder, reference the permissions of a template folder, assign those same permissions to the new folder, and then grant the user access to the new folder.

Logs: 
What about logging your steps so that they can be audited later? Does your organization require that this process have auditable logs? Many organizations do. You may choose to log the execution of the script verbosely, but verboseoutput will be difficult for auditors to read unless they know PowerShell. In this script, our log has predefined text fields and variables are inserted into the logs that contain the items required by most auditors. These items include date, username, security groups, e-mail addresses, mailbox settings (such as ActiveSync), and more. 

# Write logs to log file ******************************************************
#Append text file to confirming actions taken
$UserGroups = (Get-ADPrincipalGroupMembership $Username).name
Add-Content "\\ ScriptLogPath \$username.txt" "Create User: $Fullname"
Add-Content "\\ScriptLogPath\$username.txt" " "
Add-Content “\\ScriptLogPath\$username.txt” "DateTime: $DTStamp"
Add-Content “\\ScriptLogPath\$username.txt” "Account Enabled: $Status"
Add-Content “\\ScriptLogPath\$username.txt” "Email: $Email"
#$MailStatus = Get-Mailbox $Username
Add-Content “\\ScriptLogPath\$username.txt” "Mailbox Created: $MailStatus"
Add-Content “\\ScriptLogPath\$username.txt” "Department: $Department"
Add-Content “\\ScriptLogPath\$username.txt” "Copied from: $Peer"
Add-Content “\\ScriptLogPath\$username.txt” "Group Membership: $UserGroups"
Add-Content “\\ScriptLogPath\$username.txt” "ADUC Location: $UserCan"
Add-Content “\\ScriptLogPath\$username.txt” "ipPhone: $ipPhone"
Add-Content “\\ScriptLogPath\$username.txt” "$Username P Drive created at $HomePath\$Username"
Add-Content “\\ScriptLogPath\$username.txt” "$Username N Drive created at $AppPath\$Username"
Add-Content “\\ScriptLogPath\$username.txt” "Errors:"
Add-Content “\\ScriptLogPath\$username.txt” "$Err1"
Add-Content “\\ScriptLogPath\$username.txt” "$Err2"
Add-Content “\\ScriptLogPath\$username.txt” "$Err3"
Add-Content “\\ScriptLogPath\$username.txt” "$Err4"
Add-Content “\\ScriptLogPath\$username.txt” "__________________________________________________________________________________"
# Open log file for viewing at script completion *****************************
& “\\ScriptLogPath\$username.txt”

​Security Badges & Tokens:
Many organizations today utilize security badges or tokens as a Physical Access control. Usually this is part of the onboarding process, otherwise the new employee wouldn’t e able to move around the building. Explaining the rules around accessing certain rooms to every new administrator is important, but leaves room for interpretation. What access should they be granted? Is that based on variables such as role, department, location, gender, etc? If so, those rules can be written into your PowerShell script so that your administrator doesn't have to use their judgement on this step each time. Because every organization uses a different system, and for security measures, I haven’t included commands for this function in my public scripts. I place this section here though to stimulate your mind of the possibilities.

For automating the off-boarding (or terminating) of employees check out my article  Off-Boarding (Terminating) Users with PowerShell. ​