Skip to content

How To: Offboard A User In Office 365

    Offboarding a user in Office 365/Exchange or from an organization is always complicated. Some checklists handle stuff like this, which many MSPs and MSSPs have in-house – but much of this work is done manually and can cause important things to fall through the cracks. So, we will walk you through our process to take care of stuff like this with downloadable PowerShell scripts!

    Items that are not covered in this article are:

    • User Disablement – Not all AD or 365 implementations are the same. You may have a different process for terminating user accounts or terminating access. Those will not be covered here.
    • Older versions of PowerShell – If you are running an older version of PowerShell, it is advised that you update to the latest stable version. These commands may or may not work on older PS shells.

    Disclaimer: We don’t take any responsibility for these scripts, and there is no warranty of any kind. It is up to you to ensure these will work in your environment without breaking anything. By cut and pasting these into your environment, you are accepting any and all risks associated. None of these scripts are designed to delete anything or cause irreparable damage to your Office 365 infrastructure, but I want to put this disclaimer out there.

    Find All Associated Mailbox Aliases For Exchange 365 Mailbox Using PowerShell

    We have a post that will show you how to list all mailbox aliases for an Office 365 User, but here is the PowerShell Script that you can customize for your needs. This script can be run from your local machine or a server with a supported PowerShell version installed.

    It is important to know what aliases are assigned to a particular user, because as people enter and leave a company, other users – especially managers – tend to snowball aliases over time. We had a long-time director here at Atec that was around for 20-odd years, and he had over a dozen aliases that we didn’t know about when that director moved onto another organization. So, this should be the first step in the offboarding process because unless you are keeping a detailed list of who has what email alias hanging off their mailbox in Office 365 (or Exchange) – this information is not the most forthcoming, and you often don’t find out until after you completely decommission the mailbox.

    Step 1: Make sure you have the Exchange Online Management module installed. You can do this by running the following in PowerShell: 

    Install-Module -Name ExchangeOnlineManagement

    Step 2: Once you have that running, copy the following into a blank file, and name it something descriptive like ListAliases.ps1 or whatever will help you differentiate this from other scripts you run. 

    # Import The PowerShell module for Exchange Online 
Import-Module ExchangeOnlineManagement 

# Connect to Exchange Online 
Connect-ExchangeOnline -UserPrincipalName yourusername@yourdomain.com 

# Show Email Addersses For Decomissioned User
Get-Mailbox user@whatever.com | select -ExpandProperty emailaddresses | Select-String -Pattern "smtp"

    username@whatever.com can be replaced with the username of the user who is being offboarded. This will show a list of email addresses the outgoing user has associated with their mailbox.

    Now that you know what aliases are in that mailbox, you can decide which ones you want to reassign and which you can potentially get rid of. We recommend keeping a detailed accounting of what aliases are assigned to which user.

    Reassign Office 365 Email Alias With PowerShell

    To do this, you must remove the alias from the departing employee’s mailbox before you can assign it to another mailbox. Here is a PowerShell Script that will do precisely that in a single execution.

    Change the following variables to make this work:

    • $outgoingUser – This is who is leaving the company
    • $aliasRecipient – This is who is getting the new alias
    • $aliasValue – This is what the alias is
    # Import and Connection Block
Import-Module ExchangeOnlineManagement 
Connect-ExchangeOnline -UserPrincipalName your365login@domain.com 

# Variable declaration 
$outgoingUser = "outgoinguser@domain.com"
$aliasRecipient = "aliasrecipient@domain.com"
$aliasValue = "thealias@domain.com"

# Remove the alias
Set-Mailbox $outgoingUser -EmailAddresses @{Remove=$aliasValue}

# Add the alias to the new recipients mailbox
Set-Mailbox $aliasRecipient -EmailAddresses @{Add=$aliasValue}

    Export Office 365 User Mailbox To PST File Using PowerShell

    .PST files are the best way to store archived email data. Some companies will keep mailboxes live for a while by converting them to shared mailboxes and assigning them to another user so they can go back and look through stuff. Keeping mailboxes hanging around for a while can make your security footprint bigger than you would want it to be, so the best practice is to give that user’s old email address to a manager in the form of an alias. So do that, you have to decommission the departing user’s mailbox completely. Before decommissioning, you will want to back it up to PST.

    Prerequisites To Exporting Mailboxes in 365 to PST

    You will need proper permissions to do this set. You need:

    • You need to be an eDiscovery Admin or eDiscovery Manager
    • You will need Connect-MsolService installed

    You can check to make sure you have the proper permissions by running the following: 

    # Connect to Microsoft Online
Connect-IPPSSession

# Get permissions 
Get-eDiscoveryCaseAdmin

    If your name does not appear in that list, you must add the permission to yourself.

    You can add yourself or whoever will be executing this by entering the following: 

    Add-eDiscoveryCaseAdmin -User <xyz>@contoso.com

    Once you execute that, Get-eDiscoveryCaseAdmin again and verify that your name is showing up in the list.

    Execute the search and prepare the PST file download

    Now that you have the correct permissions assigned, modify and run the script in the code block below

    Important: After the script runs, you are not ready to download the PST yet! Office 365 still needs to output it and build the PST file to completion. If you are downloading a rather large mailbox, you will have to wait some time. You can check the progress by going here: https://compliance.microsoft.com/contentsearchv2?viewid=export – click on the export, and in the view that appears on the right side, look at “status.” Only when that bar is complete can you use the URL to directly download the PST file. This process can take up to 24 hours or more depending on how huge the inbox is that you are exporting!

    # Instantiate the connection to the Office 365 Compliance Center (Purview)
Connect-IPPSSession

$departedUser = "username@email.com"
$uniqueCaseName = "unique_name_for_export"

# Creates the compliance case that we will use to export the mailbox items
New-ComplianceSearch -Name $uniqueCaseName -ExchangeLocation $departedUser | Start-ComplianceSearch

# This line will tell it to do an export of data that was found
New-ComplianceSearchAction -SearchName $uniqueCaseName -Export

# This will get the URL and the key that you will need to download the PST file in question
Get-ComplianceSearchAction -IncludeCredential | where {$_.name -eq $uniqueCaseName}| fl

    Conclusion

    These scripts don’t account for the totality of decommissioning an end-user, but they automate a lot of the clicky work we like to avoid.

    Tags: