Add function to wrap common user offboarding tasks

[scrthq]

Talking in the PowerShell Slack and generalized the function that I'm using internally:

function Invoke-GSUserOffboarding {
    [CmdletBinding(SupportsShouldProcess,ConfirmImpact = "High")]
    Param(
        [Parameter(Mandatory,Position = 0,ValueFromPipeline,ValueFromPipelineByPropertyName)]
        [Alias('PrimaryEmail','Mail')]
        [string[]]
        $User,
        [Parameter()]
        [ValidateSet('Full','ClearASPs','ClearOAuthTokens','RemoveMobileDevices','Suspend','SetRandomPassword','MoveToOrgUnit','SetLicense')]
        [String[]]
        $Options = @('ClearASPs','ClearOAuthTokens','RemoveMobileDevices','Suspend','SetRandomPassword'),
        [Parameter()]
        [string]
        $DestinationOrgUnit,
        [Parameter()]
        [ValidateSet("G-Suite-Enterprise","Google-Apps-Unlimited","Google-Apps-For-Business","Google-Apps-For-Postini","Google-Apps-Lite","Google-Drive-storage-20GB","Google-Drive-storage-50GB","Google-Drive-storage-200GB","Google-Drive-storage-400GB","Google-Drive-storage-1TB","Google-Drive-storage-2TB","Google-Drive-storage-4TB","Google-Drive-storage-8TB","Google-Drive-storage-16TB","Google-Vault","Google-Vault-Former-Employee","1010020020")]
        [string]
        $License = "Google-Vault-Former-Employee"
    )
    Begin {
        function New-RandomPassword {
            Param (
                [parameter(Mandatory = $false)]
                [int]
                $Length = 15
            )
            $ascii = $null
            for ($a = 33;$a –le 126;$a++) {
                $ascii += ,[char][byte]$a
            }
            for ($loop = 1; $loop –le $length; $loop++) {
                $randomPassword += ($ascii | Get-Random)
            }
            return ([String]$randomPassword)
        }
    }
    Process {
        foreach ($U in $User) {
            if ($PSCmdlet.ShouldProcess("Offboarding user: $U")) {
                $user = @{User = $U}
                $updateParams = @{Confirm = $false}
                foreach ($opt in $options) {
                    switch -RegEx ($opt) {
                        '(Full|Suspend)' {
                            $updateParams['Suspended'] = $true
                        }
                        '(Full|SetRandomPassword)' {
                            $updateParams['Password'] = ConvertTo-SecureString (New-RandomPassword) -AsPlainText -Force
                            $updateParams['ChangePasswordAtNextLogin'] = $true
                        }
                        '(Full|MoveToOrgUnit)' {
                            if ($PSBoundParameters.ContainsKey('DestinationOrgUnit')) {
                                $updateParams['OrgUnitPath'] = $PSBoundParameters['DestinationOrgUnit']
                            }
                            else {
                                throw "No DestinationOrgUnit provided!! Stopping further processing"
                                exit 1
                            }
                        }
                    }
                }
                "[$(Get-Date -Format G)] [$U] Updating user"
                Update-GSUser @user @updateParams | Format-List PrimaryEmail,@{N = "FullName";E = {$_.name.fullName}},Suspended,ChangePasswordAtNextLogin,OrgUnitPath
                if ($Options -contains 'Full' -or $Options -contains 'ClearASPs') {
                    "[$(Get-Date -Format G)] [$U] Retrieving App Specific Passwords to remove"
                    $ASPs = Get-GSUserASPList @user
                    if ($ASPs) {
                        foreach ($ASP in $ASPs) {
                            "[$(Get-Date -Format G)] [$U] Revoking ASP for '$($ASP.name)'"
                            Remove-GSUserASP @user -CodeID $ASP.codeId -Confirm:$false
                        }
                        Remove-Variable ASPs -ErrorAction SilentlyContinue
                    }
                    else {
                        "[$(Get-Date -Format G)] [$U] User has no ASP's to remove!"
                    }
                }
                if ($Options -contains 'Full' -or $Options -contains 'ClearOAuthTokens') {
                    "[$(Get-Date -Format G)] [$U] Retrieving OAuth Tokens to remove"
                    $Tokens = Get-GSUserTokenList @user
                    if ($Tokens.clientId) {
                        foreach ($Token in $Tokens) {
                            "[$(Get-Date -Format G)] [$U] Revoking OAuth Token for '$($Token.displayText)'"
                            Remove-GSUserToken @user -ClientID $Token.clientId -Confirm:$false
                        }
                        Remove-Variable Tokens -ErrorAction SilentlyContinue
                    }
                    else {
                        "[$(Get-Date -Format G)] [$U] User has no OAuth Tokens to remove!"
                    }
                }
                if ($Options -contains 'Full' -or $Options -contains 'RemoveMobileDevices') {
                    "[$(Get-Date -Format G)] [$U] Retrieving Mobile Devices to remove"
                    $Mobiles = Get-GSMobileDeviceList @user -Projection BASIC
                    if ($Mobiles) {
                        foreach ($Mobile in $Mobiles) {
                            "[$(Get-Date -Format G)] [$U] Removing Mobile Device '$($Mobile.model)'"
                            Remove-GSMobileDevice -ResourceID $Mobile.resourceId -Confirm:$false
                        }
                        Remove-Variable Mobiles -ErrorAction SilentlyContinue
                    }
                    else {
                        "[$(Get-Date -Format G)] [$U] User has no Mobile Devices to remove!"
                    }
                }
                if ($Options -contains 'Full' -or $Options -contains 'SetLicense') {
                    if ($null -ne $License) {
                        "[$(Get-Date -Format G)] [$U] Setting user license to: $License"
                        Set-GSUserLicense @user -License $License | Format-List UserId,ProductId,SkuId
                    }
                }
            }
        }
    }
}

[scrthq]

released in v2.35.0