Automating onboard process with PowerShell (v1)

/ Instructional / By

Purpose:

I have developed a similar script for my company months back and just decided today to cover the first version of it. I love automating any task that is done more then once. It saves a lot of time and allows me to focus my attention on other projects. This version was before I started implementing parameters into my scripts which will be covered in another detailed writeup highlighting parameters later on.

Script source code

# Create timespan for account expiry
$tspan = New-Timespan -Days 365

# Ask user for unit
$unitlist = @('Org1','Org2')
$Unit = Read-Host "Please enter unit (Org1,Org2)"

# Input validation
if ($Unit -in $unitlist){
    Clear-Host
}
# Unit Does not exist, exit program
Else{
    Write-Host "Unit does not exist."
    Start-Sleep -Seconds 10
    Exit
}

# Get user information
$fname = Read-Host "Please enter first name"
$lname = Read-Host "Please enter last name"
$sname = ($fname + '.' + $lname)
$dname = ($fname + ' ' + $lname)
$upn = ($sname + '@cyberme.local')
$tDate = Get-Date -Format "yyyy/MM/dd"
$accexpire = (Get-DAte) + $tspan

# Copy user template based on input
if ( $Unit.ToLower() -eq 'org1' ){
    #Org1
    $u = Get-ADUser -Identity _Template1 -Properties Description,Office,OfficePhone
    # Get User Groups from Template
    $ugroups = Get-ADPrincipalGroupMembership -Identity _Template1
    # Create user
    New-ADUser -SamAccountName $sname -Instance $u -UserPrincipalName $upn -Surname $lname -GivenName $fname -Name $dname -Description ("Reviewed:"+$tDate) -AccountExpirationDate $accexpire
    # Give user groups
    $ugroups | foreach { Add-ADPrincipalGroupMembership -Identity $sname -MemberOf $_ -ErrorAction SilentlyContinue }
}
elseif ( $Unit.ToLower() -eq 'org2' ){
    # Org2
    $u = Get-ADUser -Identity _Template2 -Properties Description,Office,OfficePhone
    # Get User Groups from Template
    $ugroups = Get-ADPrincipalGroupMembership -Identity _Template2
    # Create user
    New-ADUser -SamAccountName $sname -Instance $u -UserPrincipalName $upn -Surname $lname -GivenName $fname -Name $dname -Description ("Reviewed:"+$tDate)
    # Give user groups
    $ugroups | foreach { Add-ADPrincipalGroupMembership -Identity $sname -MemberOf $_ -ErrorAction SilentlyContinue }
}

# Verify results
Clear-Host
Write-Host "Account created for: $sname"
Write-Host "Properties of user:"
Start-Sleep -Seconds 0
Get-ADUser -Identity $sname -Properties *
# Enable Account
$userenable = Read-Host "Would you like to enable account for $sname? (y/n): "
if ($userenable.ToLower() -eq 'y'){
    Set-ADAccountPassword -Identity $sname -Reset 
    write-host "Enabled"
    Enable-ADAccount -Identity $sname
}
# Keep Account disabled
elseif ($userenable.ToLower() -eq 'n') {
    write-host "Disabled"
}
# Input validation
else{
    write-host "Error: unable to compute human idiocracy"
    Start-Sleep -Seconds 5
    Exit
}

Breakdown

# Create timespan for account expiry
$tspan = New-Timespan -Days 365

To begin this script we will define all of our variables. Starting with a Timespan. Using the New-Timespan cmdlet we are able to define an amount of days to later be used in calculating account expiration. In this case 365 days. This will be stored in a date-time object so we can add to the date object later.

Example: 

# Ask user for unit
$unitlist = @('Org1','Org2')
$Unit = Read-Host "Please enter unit (Org1,Org2)"

Next, we will ask the administrator what unit (office) the member belongs to. We will assign this value $Unit variable. We will also create an array to store the two organizations.

# Input validation
if ($Unit -in $unitlist){
    Clear-Host
}

Before going any further it is best we perform input validation to ensure the unit exists. We will use the if statement and ask if $Unit is -in $unitlist. If $Unit does exist then clear-host and continue script. 

# Unit Does not exist, exit program
Else{
    Write-Host "Unit does not exist."
    Start-Sleep -Seconds 10
    Exit
}

We will catch any errors with the Else statement and inform the administrator that the organization entered does not exist, and exit the program after 10 seconds. 

# Get user information
$fname = Read-Host "Please enter first name"
$lname = Read-Host "Please enter last name"
$sname = ($fname + '.' + $lname)
$dname = ($fname + ' ' + $lname)
$upn = ($sname + '@cyberme.local')
$tDate = Get-Date -Format "yyyy/MM/dd"
$accexpire = (Get-Date) + $tspan

At this point we are going to again use Read-Host cmdlet asking administrator for input such as first and last name. From here we will then manipulate the two and assign them to various variables later used in creating this account. For example $dname will be used as display name, and $upn will be used as user principal name. We then at this point also want to grab todays date using Get-Date cmdlet. We also used the -Format option in order to get the yyyy/MM/dd format. Lastly, we assign the account expire variable $accexpire 365 days from today.

# Copy user template based on input
if ( $Unit.ToLower() -eq 'org1' ){
    #Org1
    $u = Get-ADUser -Identity _Template1 -Properties Description,Office,OfficePhone
    # Get User Groups from Template
    $ugroups = Get-ADPrincipalGroupMembership -Identity _Template1
    # Create user
    New-ADUser -SamAccountName $sname -Instance $u -UserPrincipalName $upn -Surname $lname -GivenName $fname -Name $dname -Description ("Reviewed:"+$tDate) -AccountExpirationDate $accexpire
    # Give user groups
    $ugroups | foreach { Add-ADPrincipalGroupMembership -Identity $sname -MemberOf $_ -ErrorAction SilentlyContinue }
}
elseif ( $Unit.ToLower() -eq 'org2' ){
    # Org2
    $u = Get-ADUser -Identity _Template2 -Properties Description,Office,OfficePhone
    # Get User Groups from Template
    $ugroups = Get-ADPrincipalGroupMembership -Identity _Template2
    # Create user
    New-ADUser -SamAccountName $sname -Instance $u -UserPrincipalName $upn -Surname $lname -GivenName $fname -Name $dname -Description ("Reviewed:"+$tDate)
    # Give user groups
    $ugroups | foreach { Add-ADPrincipalGroupMembership -Identity $sname -MemberOf $_ -ErrorAction SilentlyContinue }
}

Now we are going to actually perform the onboarding process. We will have the first if statement for org1 and elseif statement for org2. Both perform the same function but will be placed in different groups and assigned different properties based on administrators input.

Inside the if statement we want to convert $Unit to lowercase. This allows for the administrator to enter either ORG1, org1 or even OrG1. All will be passed as lowercase and compared with string value ‘org1’. Next we will get our template we want to copy properties from using Get-Aduser cmdlet and assign to $u. Based on what properties we want to copy over will be determined by the -Properties option of Get-ADUser cmdlet. We will then create a $ugroups variable to get group membership of Template1.

After grabbing user properties and group membership we will create the user using New-ADUser. With New-ADUser cmdlet we will define -SamAccountName, -Instance, UserPrincipalName, -Surname, -Givenname, -Name and last but not least -Description. Inside Description is where we will use the $tDate variable to document when account was reviewed and or created. 

 $ugroups | foreach { Add-ADPrincipalGroupMembership -Identity $sname -MemberOf $_ -ErrorAction SilentlyContinue }

After creating the user we want to assign group membership. We will pipe each of the objects from $ugroups into a foreach loop. For each object assigned to $ugroups we will Add-AdPrincipalGroupMembership to the -Identity of $sname by using -MemberOf $_. $_ is used to pass through the current object being looked at. We will then use -ErrorAction to silently continue. This is necessary because if group already exists with user an error will be presented. 

# Verify results
Clear-Host
Write-Host "Account created for: $sname"
Write-Host "Properties of user:"
Start-Sleep -Seconds 0
Get-ADUser -Identity $sname -Properties *

Once we had created the user we will then verify the results and post them to the shell for administrator to verify. We will display the user properties by using Get-ADUser and use a wildcard for -Properties option.

# Enable Account
$userenable = Read-Host "Would you like to enable account for $sname? (y/n): "
if ($userenable.ToLower() -eq 'y'){
    Set-ADAccountPassword -Identity $sname -Reset
    write-host "Enabled"
    Enable-ADAccount -Identity $sname
}

Finally we will ask the administrator if the new user account should be enabled or not. If the answer equals ‘y’, the account will be enabled using Enable-ADAccount. Before doing so, we must reset the password using the Set-ADAccountPassword cmdlet.

# Keep Account disabled
elseif ($userenable.ToLower() -eq 'n') {
    write-host "Disabled"

If the user is to stay disabled then we will write to screen informing administrator that account is Disabled.

# Input validation
else{
    write-host "Error: unable to compute human idiocracy"
    Start-Sleep -Seconds 5
    Exit
}

To end the script we will use an else statement to catch any other input other then y/n.

Conclusion

That covers everything for this onboarding script with PowerShell. As I mentioned in the original purpose statement, I will be doing a second post here soon covering version 2 of the onboard script. Version 2 will go into detail covering parameters inside of a PowerShell script. Allowing the administrator to input nearly all of the options asked in this script but onto one line. For example
./onboard.sh -org org1 -fname Jack -lname Harlow -enabled

Pretty much everything in current script described above with ‘read-host’ will have a parameter. Allowing for execution of script without having to follow prompts.

GitHub

https://github.com/CyberMe-Jack/Powershell_Scripts/blob/main/CreateUser_V1.ps1