How to Build an AD App for Onboarding Users
The world of managing Active Directory users in some organizations could be a full-time job in and of itself. With as versatile as technology support specialists must be these days, having any automation skill is welcome.
One of the most tedious tasks with creating new users in Active Directory Users & Computers (ADUC) is adding all the required settings and properties on user accounts. The more users you are looking to onboard and the more complex your environment is can really make this process a burden.
Leveraging PowerShell, let's look at a simple script that can serve as a framework for you and your team that can be used as is, and also can easily be customized to fit your domain environment when it comes to onboarding new users in Active Directory. This article will be using the provided script hosted on GitHub here.
Build the Script Interface
Don't be intimidated by that sub-heading. This will be an extremely simple interface that will prompt for the information you are needing to build the user account. The example script used for this article will prompt for the first and last name as separate inputs. Then a simple numbered list will show the different departments that may exist in your organization. Simply choose the department by number and press enter. The script will do the rest!
When you run this script, you will need to enter three pieces of information:
User first name
User last name
Department (represented by a number)
Write-Host “This script will take the First Name and Last Name of a new user and stage them for work in the Department that is chosen.”
$UserFirstname = Read-Host “Enter the first name of the user whom you want to Onboard”
$UserLastname = Read-Host “Enter the last name of the user whom you want to Onboard”
Write-Host -foregroundcolor Yellow “What Department is this user going to be in?”
Write-host -foregroundcolor Gray ”
1> Manufacturing 2> Accounting
3> Department C 4> Department D
5> Department E”
$Department = Read-Host “Enter the department #”
This will build the interface as such:
It is built out by some simple Read-Host cmdlets and a quick and dirty "menu" of sorts of the different departments. Department distinction is set by use of the switch statement. Microsoft Docs has some information on the switch statement.
The $Department variable is set with the Read-Host statement asking for the department #:
Switch ($Department){
1 {$Department = “Manufacturing”}
2 {$Department = “Accounting”}
3 {$Department = “Department C”}
4 {$Department = “Department D”}
5 {$Department = “Department E”}
}
If the username convention is firstname.lastname, you can build out the username and the home directory path. Notice the .ToLower() option, which will force all the letters in the username to lowercase, no matter how they were entered. The following will set the username along with the home drive path:
$SAMAccountName = (“$UserFirstname” + “.” + “$UserLastname”).ToLower()
$HomeDrivePath = “\\fs01\users\” + “$SAMAccountName”
Build the User Object
A best practice is to build any user account the same exact way every single time. This script does just that, right from the onset. The most generic properties and settings that all users in your domain have should be built here. The distinct properties, settings, and configurations then are branched off according to the department input after the base account is built.
Now that variables are set, you can build out the initial account with the following parameters:
Places the account in a "generic" location. The account must get created somewhere, so it's created in a general OU and the switch statement blocks will move it to where it needs to be, then enables the account
Sets the password to a generic (temporary) and forces a change on first logon
Sets the names (SAMaccount, display name, etc)
Sets the description to the chosen value for $Department
Sets the Office value, this is a static site location for me
A success message is included for this step for confirmation, along with the catch side if there is an error and it will be displayed. A break is included in the catch block here because if there is a problem creating the account, most likely the rest of the tasks will fail:
try {
Write-Host
Write-Host “Creating the initial account: $SAMAccountName…”
Write-Host
New-ADUser -Name “$UserFirstname $UserLastname” -GivenName “$UserFirstname” -Surname “$UserLastname”
-Path "OU=Users,OU=Site,DC=domain,DC=com"
-UserPrincipalName (“$SAMAccountName” + ‘@’ + “domain.com”)
-AccountPassword (ConvertTo-SecureString -AsPlainText "Temporary" -force)
-ChangePasswordAtLogon $true
-SamAccountName "$SAMAccountName"
-Enabled $true
-DisplayName "$UserFirstname $UserLastname"
-Description “$Department”
-Office "Your City"
Write-Host “SUCCESS: The user account: $SAMAccountName has been created!” -ForegroundColor Green
Write-Host
}
catch {
$ErrorMessage = $_.Exception.Message
Write-Host “WARNING: Error in creating the account: $ErrorMessage” -ForegroundColor Red -BackgroundColor Black
Write-Host
Read-Host -Prompt “Press Enter to exit…”
break
}
Notice that the account password is being forced as 'Temporary' (in plain text). Due to this being a quick way to get this process up and running, setting the password should be discussed with your Security Operations team to come up with a way to set a temporary password securely from a .txt file using the ConvertTo-SecureString cmdlet. Otherwise, anyone who has access to this script will then know what the initial password is for all new accounts.
Build Department Properties
Based on the input of the department number, certain department-specific properties are set. Some of them may be:
User object department information and/or description
AD security group membership
Setting home directory letter and path
Move user object to production OU
Notice the switch($Department){ at the beginning. This kicks in the switch value based on the number entered for the correlating department. You then match the department "block" with one of the variables for $Departments. Notice that the entire switch block and each individual part have their own set of curly braces {}:
switch($Department){
“Manufacturing” {
$Groups = Get-content “C:\Scripts\DepartmentGroups\Manufacturing.txt”
Write-Host “Adding the account to the following AD security groups: $Groups”
try {
foreach ($Group in $Groups){
Add-ADGroupMember -Identity “$Group” -Members “$SAMAccountName”
}
Write-Host “SUCCESS” -ForegroundColor Green
Write-Host
}
catch {
$ErrorMessage = $_.Exception.Message
Write-Host “WARNING: Error in adding to AD security groups: $ErrorMessage” -ForegroundColor Red -BackgroundColor Black
Write-Host
Read-Host -Prompt “Press Enter to exit…”
break
}
AD group names are set from pre-filled .txt files for each department — given that the group memberships for new accounts don't really change much, if at all. All that is in the .txt file is the AD security group name(s), one per line. As you can also see, a success/fail structure is set with the try/catch block.
Write-Host “Moving AD user object to its proper OU…”
Write-Host
try {
Get-ADUser -Identity $SAMAccountName | Move-ADObject -TargetPath “OU=Manufacturing,OU=Users,DC=domain,DC=com”
Write-Host “SUCCESS” -ForegroundColor Green
Write-Host
}
catch {
$ErrorMessage = $_.Exception.Message
Write-Host “WARNING: Error in moving to OU: $ErrorMessage” -ForegroundColor Red -BackgroundColor Black
Write-Host
Read-Host -Prompt “Press Enter to exit…”
break
}
Write-Host “Account created and staged successfully!”
Read-Host -Prompt “Press Enter to exit”
Notice the catch block contains a break command to stop the script should any part fail. This way the catch and error message will indicate where the problem is. A final success message and a Read-Host is present, so the console window doesn't disappear and you don't get a chance to read the success/error lines.
This next example will display the part that is different from the previous example: it will define home drive letter/path/folder. This can be dropped into any of the department blocks as needed. Remember, if every account gets a home directory, then this could be moved to the initial account buildout phase and not repeated in every department block.
Write-Host “Setting the home drive letter to H: and adding the path…”
try {
Set-ADUser -Identity $SAMAccountName -HomeDrive “H:” -HomeDirectory $HomeDrivePath
Write-Host “SUCCESS” -ForegroundColor Green
}
catch {
$ErrorMessage = $_.Exception.Message
Write-Host “WARNING: Error in setting the home drive letter/path: $ErrorMessage” -ForegroundColor Red -BackgroundColor Black
Write-Host
Read-Host -Prompt “Press Enter to exit…”
break
}
Write-Host “Creating the home folder and setting permissions…”
try {
$HomeShare = New-Item -Path $HomeDrivePath -ItemType Directory -Force
$ACL = Get-Acl $HomeShare
$AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule (“DOMAIN\$SAMAccountName”, “Modify”, “ContainerInherit, ObjectInherit”, “InheritOnly”, “Allow”)
$ACL.AddAccessRule($AccessRule)
$AccessRule = New-Object System.Security.AccessControl.FileSystemAccessRule (“DOMAIN\$SAMAccountName”, “Modify”, “None”, “InheritOnly”, “Allow”)
$ACL.AddAccessRule($AccessRule)
Set-Acl -Path $HomeShare -AclObject $ACL
Write-Host “SUCCESS” -ForegroundColor Green
Write-Host
}
catch {
$ErrorMessage = $_.Exception.Message
Write-Host “WARNING: Error in creating the home drive folder: $ErrorMessage” -ForegroundColor Red -BackgroundColor Black
Write-Host
Read-Host -Prompt “Press Enter to exit…”
break
}
The first part of this is straightforward. Setting the home drive letter/path is easy. The tricky part is not creating the folder on the file server but setting the proper permissions on the share. This process will give the user Modify rights on their home directory.
What's Next? Build More!
This is a very simple framework that can not only be used right away after making some quick customizations to fit your environment but can also be a foundation for many other add-ins and tasks that go along with creating new users. Starting out with just the basics can help you to understand the process and will quickly evolve and grow as you put more time and effort into it. You will soon start to find all kinds of tasks and features you can throw in to further automate the onboarding process.
The next step could be adding email notifications using Send-MailMessage to notify department management about new account creation, logging of newly created accounts, and eventually morph into a bulk-account creation workflow. Once the initial framework is in place, it can easily grow and fit into your environment. When learning the extensive features of PowerShell, sometimes it just takes a simple framework to start and you can take off from there!
delivered to your inbox.
By submitting this form you agree to receive marketing emails from CBT Nuggets and that you have read, understood and are able to consent to our privacy policy.