A Repeatable Microsoft 365 Offboarding Script with Graph PowerShell

Install-Module Microsoft.Graph -Scope CurrentUser
Install-Module ExchangeOnlineManagement -Scope CurrentUser

<#
.SYNOPSIS
  Offboards a Microsoft 365 user: disable, revoke, convert mailbox,
  delegate to manager, remove groups and licenses, then email HR
  and the manager a confirmation.
.EXAMPLE
  .\Invoke-M365Offboarding.ps1 -UserPrincipalName jdoe@example.com -WhatIf
.EXAMPLE
  .\Invoke-M365Offboarding.ps1 -UserPrincipalName jdoe@example.com -HrAddress hr@example.com
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    [Parameter(Mandatory)]
    [string]$UserPrincipalName,

    # Optional override if the manager isn't set in Entra ID
    [string]$DelegateTo,

    # Where the confirmation email goes (in addition to the manager)
    [string]$HrAddress = 'hr@example.com'
)

$ErrorActionPreference = 'Stop'
$log = [System.Collections.Generic.List[string]]::new()

Connect-MgGraph -Scopes 'User.ReadWrite.All','Group.ReadWrite.All','Directory.ReadWrite.All','Mail.Send' -NoWelcome
Connect-ExchangeOnline -ShowBanner:$false

$user = Get-MgUser -UserId $UserPrincipalName -Property Id,DisplayName,UserPrincipalName,AssignedLicenses

# Resolve the manager (used for mailbox delegation and the confirmation email)
$managerUpn = $null
try {
    $mgr = Get-MgUserManager -UserId $user.Id
    $managerUpn = $mgr.AdditionalProperties['userPrincipalName']
} catch { Write-Warning 'No manager set in Entra ID.' }

if (-not $DelegateTo) { $DelegateTo = $managerUpn }
if (-not $DelegateTo) { Write-Warning 'No delegate found; mailbox will not be delegated.' }

# 1-2. Disable sign-in and revoke sessions
if ($PSCmdlet.ShouldProcess($UserPrincipalName, 'Disable account and revoke sessions')) {
    Update-MgUser -UserId $user.Id -AccountEnabled:$false
    Revoke-MgUserSignInSession -UserId $user.Id | Out-Null
    $log.Add('The account has been disabled and all sign-in sessions have been revoked.')
}

# 3. Convert the mailbox to shared and hide it from the GAL
if ($PSCmdlet.ShouldProcess($UserPrincipalName, 'Convert mailbox to shared')) {
    Set-Mailbox -Identity $UserPrincipalName -Type Shared
    Set-Mailbox -Identity $UserPrincipalName -HiddenFromAddressListsEnabled $true
    $log.Add('The mailbox has been converted to a shared mailbox and hidden from the address list.')
}

# 4. Delegate mailbox access
if ($DelegateTo -and $PSCmdlet.ShouldProcess($UserPrincipalName, "Grant Full Access to $DelegateTo")) {
    Add-MailboxPermission -Identity $UserPrincipalName -User $DelegateTo `
        -AccessRights FullAccess -InheritanceType All -AutoMapping $true | Out-Null
    $log.Add("$DelegateTo has been granted access to the mailbox.")
}

# 5. Remove cloud group memberships (skip dynamic and mail-enabled groups)
$groups = Get-MgUserMemberOf -UserId $user.Id -All |
    Where-Object { $_.AdditionalProperties['@odata.type'] -eq '#microsoft.graph.group' }

foreach ($g in $groups) {
    $types      = $g.AdditionalProperties['groupTypes']
    $mail       = $g.AdditionalProperties['mailEnabled']
    $isUnified  = $types -contains 'Unified'
    $isDynamic  = $types -contains 'DynamicMembership'
    $name       = $g.AdditionalProperties['displayName']

    if ($isDynamic) { continue }  # membership is rule-based

    if ($mail -and -not $isUnified) {
        # Distribution lists / mail-enabled security groups are managed in Exchange
        if ($PSCmdlet.ShouldProcess($name, 'Remove from distribution group')) {
            Remove-DistributionGroupMember -Identity $g.AdditionalProperties['mail'] -Member $UserPrincipalName `
                -BypassSecurityGroupManagerCheck -Confirm:$false
        }
    }
    elseif ($PSCmdlet.ShouldProcess($name, 'Remove from group')) {
        Remove-MgGroupMemberByRef -GroupId $g.Id -DirectoryObjectId $user.Id
    }
}
# 6. Remove directly assigned licenses (after mailbox conversion)
$skuIds = @($user.AssignedLicenses.SkuId)
if ($skuIds.Count -and $PSCmdlet.ShouldProcess($UserPrincipalName, 'Remove licenses')) {
    try {
        Set-MgUserLicense -UserId $user.Id -AddLicenses @() -RemoveLicenses $skuIds | Out-Null
    } catch {
        Write-Warning "Some licenses may be group-assigned and were removed with group membership: $_"
    }
}
if (-not $WhatIfPreference) { $log.Add('Group memberships and licenses have been removed.') }

# 7. Build the summary and email HR and the manager
$summary = @"
This is to confirm that $($user.DisplayName) ($UserPrincipalName) has been offboarded as of $(Get-Date -Format 'MM-dd-yyyy').

$(($log | ForEach-Object { "  * $_" }) -join "`n")
"@

$recipients = @($HrAddress, $managerUpn) | Where-Object { $_ } | Select-Object -Unique

if ($PSCmdlet.ShouldProcess(($recipients -join ', '), 'Send offboarding confirmation')) {
    $mail = @{
        Message = @{
            Subject      = "Offboarding complete: $($user.DisplayName)"
            Body         = @{ ContentType = 'Text'; Content = $summary }
            ToRecipients = @($recipients | ForEach-Object { @{ EmailAddress = @{ Address = $_ } } })
        }
        SaveToSentItems = $true
    }
    $sender = (Get-MgContext).Account
    Send-MgUserMail -UserId $sender -BodyParameter $mail
    Write-Host "Confirmation sent to: $($recipients -join ', ')"
}

$summary