Automated Employee Offboarding via PowerShell

Have you ever found yourself managing an on-prem Active Directory hybrid environment alongside Office 365? If so, you’ve likely encountered the task of offboarding employee accounts promptly. As organizations evolve to become more intricate and demand stricter security protocols, automation becomes indispensable to ensure consistent execution of offboarding procedures.

The aim of this article is to showcase a comprehensive automated offboarding solution I’ve developed, with the hope of inspiring others to devise their own innovative solutions. Throughout the article, I’ll provide a brief description of each component of the offboarding script, explaining its functionality, integration, and overall coherence. By doing so, I aim to offer newcomers a holistic view of the capabilities of PowerShell, illustrating how various services and modules can seamlessly collaborate together to create one coherent solution. Please note that this will be an overview and will not go into detailed step by step instructions.

Review the Current Offboarding Process

The first thing that we want to begin doing is writing out the businesses current offboarding process so we can define clear goals for our script. The current offboarding outline for our business looks like this:

The expiration date in Active Directory for the user’s account is set when HR informs the offboarding team of the employee(s) termination date.
The following day, employees ensure that the account is disabled and begin the formal offboarding process.
The users Active Directory groups and properties are saved and manually uploaded to a SharePoint folder before the AD groups are removed to ensure there’s an accurate record for documentation purposes. Some groups must remain as the business is utilizing on-prem groups that are synced to Office 365/Azure to apply various Office licenses, Exchange email being the most noteworthy.
The organization works with affiliate accounts which means with these AD accounts, they’re different in that some affiliates have a 3rd party mail contact (they do not have an organizational email). The mail contact information attributes must be removed to ensure that users are not emailing affiliates that aren’t cleared to work with the org. This removal includes various Exchange attributes in AD tied to the user(s) as well as hiding them from the Global Address List.

Define Script Goals / Pseudocoding

Import the modules and functions necessary for the script to function (we will be using one custom function).
Import credentials securely to connect to SharePoint via PowerShell PnP Module (some offboarding data will be uploaded to SharePoint).
Create user variables for processing and logging.
Disable the user(s) Active Directory account.
Exclude the necessary groups from the automated removal of groups processing.
Copy the AD users groups and properties as an easy to read txt file report to SharePoint (using PnPOnline).
Remove the groups afterwards, create a check to only remove the groups if the SharePoint copy is successful. Log any errors during this process.
Hide the user(s) from the Exchange Global Address List, remove additional Exchange attributes.
Disconnect PnPOnline session after the script has completed.
Email the offboarding team letting them know what users have been disabled & automatically offboarded. Attach an Excel spreadsheet.

The Script

Now for the fun part, we actually get to begin developing our scripting solution! While following along, please note that there is always ways to improve your script. A perfect script is one that performs what you want it to do every single time you run it with zero interaction from you. How you get there, that’s on you and your process. That being said, even with this developed solution, it will be undergoing many improvements throughout it’s life to ensure it’s updated to improve functionality and purpose.

Throughout this script development process, I will be utilizing Visual Studio Code. If you are interested in setting up a VSC environment similar to mine please review my article here that explains my current setup: https://greenetech.org/my-powershell-scripting-setup/

PowerShell 7 is also utilized, for more information on PowerShell 7 and the installation process please visit the official Microsoft documentation here: Installing PowerShell on Windows – PowerShell | Microsoft Learn

The following PowerShell modules will be utilized (please review the attached links for setup instructions for these modules).

ActiveDirectory -Info/installation instructions: ActiveDirectory Module | Microsoft Learn
ImportExcel – Installation instructions: PowerShell Gallery | ImportExcel 7.8.5
PnPOnline – Installation instructions & base setup: Installing PnP PowerShell | PnP PowerShell

Import the appropriate PowerShell modules

Set date and time variables, start a transcript for script logging purposes.

Here we are importing our credentials that are being used to connect to our SharePoint online site that has permission to access the site and upload documents to our location.

Defining the expiration date target and performing the Get-ADUser command using the proper expiration date that was stored in the $targetDate variable. Displaying the results for logging purposes.

This client has an internal SMTP server that relays messages through Office 365. An if statement was created to catch if there are no expired users to process, an email is sent notifying the offboarding team, then the script transcript stops and PowerShell is prevented from continuing the remainder of the script with the return command.

Creating a variable to exclude the groups that we do not want to remove when the automated offboarding script removes groups from the user accounts.

Building an array to easily store the user information data.

Now we’re to the core functions of the script, this will be the longest section as there are a lot of items. This section will begin the processing of each expired user that is stored in the $expiredUsers variable. This is the beginning of the foreach statement, there will be another paragraph later confirming when the foreach statement is finished.

The foreach statement is gathering information for each user and beginning the automated offboarding process. The account is disabled then we’re going to utilize try blocks to perform additional offboarding steps below.

The script begins AD Groups & Properties processing. The reports are copied and then uploaded to SharePoint. If there are any errors, the catch block will make note where this information will then be stored in the array.

Updating the msExchHideFromAddressLists attribute to $true to ensure the email is hidden in Exchange

We are now beginning the removal of mail contact information. All employees that are affiliates have either “Affiliate” or “Contingent Worker” listed as their employment type attribute. We’ve also ensured that we’ve omitted any with the name “company.net” (edited for privacy) so affiliates with a company email do not have their mail information removed.

Continuation of the above mail contact removal. A catch is included to report back any errors to the array.

We’re now taking all of our results from the offboarding commands initiated in the script for each user, creating a result object, then importing the object’s information into the array so we have an easy way to report the data for all of the users we’ve processed.

With our automated offboarding now finished, and all of the data for each user ready to be exported from our array, we’ve entered our reporting phase. The data is exported via the Export-Excel module, then attached in an SMTP email that’s relayed from an internal server to Office 365.

Now our script is finished. The last thing left to do is disconnect the PnPOnline session, write the array’s results to the log file via Write-Output, and stop the transcript so our log is ready for viewing.

Whew! That concludes our process. An important thing to note when employing ‘Connect-PnPOnline’ with SharePoint, it’s crucial to have an Azure Conditional Access policy in place to enhance security measures for the service account you’re utilizing. Now that we’ve completed this setup, our script will run daily (after midnight), automatically sending an email to the offboarding team. This email will include a report detailing user disablement and any encountered issues that require attention.

Wrapping Up

Please remember that this article doesn’t delve into every intricate step required to configure a similar solution from scratch. Its primary objective is to serve as an illustration of PowerShell’s potential with automated offboarding, with the hope of inspiring readers to devise their own solutions. Thank you for taking the time to read!