Automate Microsoft 365 User Onboarding & Offboarding with PowerShell

<#
.SYNOPSIS
    Microsoft 365 User Onboarding Script - Bulk create users from CSV
.DESCRIPTION
    Reads user data from CSV and creates users in Microsoft 365 using Microsoft Graph.
    Handles: user creation, license assignment, group membership, manager assignment.
.PARAMETER CsvPath
    Path to the CSV file containing user data
.EXAMPLE
    .onboard.ps1 -CsvPath "C:Scriptsonboard.csv"
#>

param(
    [Parameter(Mandatory=$true)]
    [string]$CsvPath,

    [string[]]$DefaultGroups = @("All Staff", "M365 Licensed Users")  # Change these to your groups
)

# Helper function to clean CSV values
function Trim-OrNull {
    param([object]$Value)
    if ($null -eq $Value) { return $null }
    $s = "$Value".Trim()
    if ([string]::IsNullOrWhiteSpace($s)) { return $null }
    return $s
}

# Normalize country codes
function Normalise-UsageLocation {
    param([string]$Location)
    if (-not $Location) { return $null }
    $loc = $Location.Trim().ToUpper()
    if ($loc.Length -eq 2) { return $loc }
    
    # Handle common full names
    switch ($loc) {
        "AUSTRALIA" { return "AU" }
        "UNITED STATES" { return "US" }
        "USA" { return "US" }
        "UNITED KINGDOM" { return "GB" }
        "UK" { return "GB" }
        default { return $loc }
    }
}

Write-Host "========================================" -ForegroundColor Cyan
Write-Host "M365 BULK USER ONBOARDING SCRIPT" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

# Check if already connected to Graph
try {
    Get-MgContext | Out-Null
    Write-Host "✅ Already connected to Microsoft Graph" -ForegroundColor Green
} catch {
    Write-Host "Connecting to Microsoft Graph..." -ForegroundColor Yellow
    Connect-MgGraph -Scopes "User.ReadWrite.All", "Group.ReadWrite.All", "Directory.ReadWrite.All" | Out-Null
    Write-Host "✅ Connected" -ForegroundColor Green
}

# Get all available licenses
Write-Host "`n📋 Fetching available licenses..." -ForegroundColor Yellow
$AllSkus = Get-MgSubscribedSku

# Find Business Premium (most common)
$BusinessSku = $AllSkus | Where-Object { 
    $_.SkuPartNumber -match "BUSINESS_PREMIUM|O365_BUSINESS_PREMIUM|STANDARDPACK" 
} | Select-Object -First 1

if (-not $BusinessSku) {
    # Try E3 if Business Premium not found
    $BusinessSku = $AllSkus | Where-Object { 
        $_.SkuPartNumber -match "ENTERPRISEPACK" 
    } | Select-Object -First 1
}

if ($BusinessSku) {
    $BusinessSkuId = $BusinessSku.SkuId
    Write-Host "✅ Found license: $($BusinessSku.SkuPartNumber)" -ForegroundColor Green
    Write-Host "   SKU ID: $BusinessSkuId" -ForegroundColor Gray
} else {
    Write-Host "❌ Could not find any license. Check your tenant." -ForegroundColor Red
    $BusinessSkuId = $null
}

# Resolve group IDs from display names
Write-Host "`n👥 Resolving group IDs..." -ForegroundColor Yellow
$GroupIdMap = @{}

foreach ($groupName in $DefaultGroups) {
    $group = Get-MgGroup -Filter "displayName eq '$groupName'" -ErrorAction SilentlyContinue
    if (-not $group) {
        # Try search if filter fails
        $group = Get-MgGroup -Search "`"displayName:$groupName`"" -ConsistencyLevel eventual -ErrorAction SilentlyContinue
    }
    
    if ($group) {
        $GroupIdMap[$groupName] = $group[0].Id
        Write-Host "✅ Found group: $groupName" -ForegroundColor Green
    } else {
        Write-Host "⚠️ Group not found: $groupName - will skip" -ForegroundColor Yellow
    }
}

# Load CSV
if (-not (Test-Path $CsvPath)) {
    Write-Host "❌ CSV not found: $CsvPath" -ForegroundColor Red
    exit
}

$Users = Import-Csv $CsvPath
Write-Host "`n📊 Loaded $($Users.Count) user(s) from CSV" -ForegroundColor Green

$successCount = 0
$failCount = 0

# Process each user
foreach ($row in $Users) {
    Write-Host "`n----------------------------------------" -ForegroundColor DarkCyan
    Write-Host "Processing: $($row.userPrincipalName)" -ForegroundColor Cyan
    
    # Get and clean all fields
    $upn = Trim-OrNull $row.userPrincipalName
    $password = Trim-OrNull $row.passwordProfile
    $displayName = Trim-OrNull $row.displayName
    $givenName = Trim-OrNull $row.givenName
    $surname = Trim-OrNull $row.surname
    $jobTitle = Trim-OrNull $row.jobTitle
    $department = Trim-OrNull $row.department
    $companyName = Trim-OrNull $row.companyName
    $managerUPN = Trim-OrNull $row.managerUPN
    $usageLoc = Normalise-UsageLocation (Trim-OrNull $row.usageLocation)
    
    # Address fields
    $street = Trim-OrNull $row.streetAddress
    $city = Trim-OrNull $row.city
    $state = Trim-OrNull $row.state
    $country = Trim-OrNull $row.country
    $postalCode = Trim-OrNull $row.postalCode
    $officeLoc = Trim-OrNull $row.officeLocation
    $mobile = Trim-OrNull $row.mobilePhone
    $phone = Trim-OrNull $row.telephoneNumber

    # Validate required fields
    if (-not $upn -or -not $password) {
        Write-Host "❌ Skipping - missing UPN or password" -ForegroundColor Red
        $failCount++
        continue
    }

    if (-not $displayName) {
        $displayName = "$givenName $surname".Trim()
    }

    # Build user object
    $userBody = @{
        accountEnabled = $true
        displayName = $displayName
        mailNickname = ($upn.Split("@")[0])
        userPrincipalName = $upn
        givenName = $givenName
        surname = $surname
        jobTitle = $jobTitle
        department = $department
        companyName = $companyName
        streetAddress = $street
        city = $city
        state = $state
        country = $country
        postalCode = $postalCode
        officeLocation = $officeLoc
        usageLocation = $usageLoc
        passwordProfile = @{
            password = $password
            forceChangePasswordNextSignIn = $true
        }
    }

    # Add optional fields
    if ($mobile) { $userBody["mobilePhone"] = $mobile }
    if ($phone) { $userBody["businessPhones"] = @($phone) }

    # Remove null values
    $cleanBody = @{}
    foreach ($key in $userBody.Keys) {
        if ($null -ne $userBody[$key]) {
            $cleanBody[$key] = $userBody[$key]
        }
    }

    # Create user
    try {
        $newUser = Invoke-MgGraphRequest -Method POST `
            -Uri "https://graph.microsoft.com/v1.0/users" `
            -Body ($cleanBody | ConvertTo-Json -Depth 5) `
            -ContentType "application/json" `
            -ErrorAction Stop
        
        $newUserId = $newUser.id
        Write-Host "✅ User created successfully" -ForegroundColor Green

        # Assign license
        if ($BusinessSkuId -and $usageLoc) {
            try {
                Set-MgUserLicense -UserId $newUserId -AddLicenses @(@{SkuId = $BusinessSkuId}) -RemoveLicenses @() -ErrorAction Stop
                Write-Host "✅ License assigned" -ForegroundColor Green
            } catch {
                Write-Host "⚠️ License assignment failed: $_" -ForegroundColor Yellow
            }
        } else {
            if (-not $usageLoc) {
                Write-Host "⚠️ Usage location missing - license not assigned" -ForegroundColor Yellow
            }
        }

        # Add to groups
        foreach ($groupName in $GroupIdMap.Keys) {
            $groupId = $GroupIdMap[$groupName]
            $body = @{
                "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/$newUserId"
            } | ConvertTo-Json

            $uri = "https://graph.microsoft.com/v1.0/groups/$groupId/members/`$ref"
            
            try {
                Invoke-MgGraphRequest -Method POST -Uri $uri -Body $body -ContentType "application/json" -ErrorAction Stop
                Write-Host "✅ Added to group: $groupName" -ForegroundColor Green
            } catch {
                Write-Host "⚠️ Failed to add to $groupName : $_" -ForegroundColor Yellow
            }
        }

        # Set manager
        if ($managerUPN) {
            try {
                $manager = Get-MgUser -UserId $managerUPN -ErrorAction Stop
                $managerBody = @{
                    "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($manager.Id)"
                }
                Set-MgUserManagerByRef -UserId $newUserId -BodyParameter $managerBody -ErrorAction Stop
                Write-Host "✅ Manager set: $managerUPN" -ForegroundColor Green
            } catch {
                Write-Host "⚠️ Failed to set manager: $_" -ForegroundColor Yellow
            }
        }

        $successCount++
        
    } catch {
        Write-Host "❌ Failed to create user: $_" -ForegroundColor Red
        $failCount++
    }
}

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "ONBOARDING COMPLETE" -ForegroundColor Cyan
Write-Host "✅ Successful: $successCount" -ForegroundColor Green
Write-Host "❌ Failed: $failCount" -ForegroundColor Red
Write-Host "========================================" -ForegroundColor Cyan

<#
.SYNOPSIS
    Microsoft 365 User Offboarding Script
.DESCRIPTION
    Automates the entire offboarding process: block sign-in, revoke sessions, remove licenses, set forwarding.
.PARAMETER CsvPath
    Path to CSV with userPrincipalName and ForwardTo columns
.EXAMPLE
    .offboard.ps1 -CsvPath "C:Scriptsoffboard.csv"
#>

param(
    [Parameter(Mandatory=$true)]
    [string]$CsvPath
)

function Trim-OrNull {
    param([object]$Value)
    if ($null -eq $Value) { return $null }
    $s = "$Value".Trim()
    if ([string]::IsNullOrWhiteSpace($s)) { return $null }
    return $s
}

Write-Host "========================================" -ForegroundColor Cyan
Write-Host "M365 BULK OFFBOARDING SCRIPT" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

# Check CSV
if (-not (Test-Path $CsvPath)) {
    Write-Host "❌ CSV not found: $CsvPath" -ForegroundColor Red
    exit
}

$Users = Import-Csv $CsvPath
Write-Host "📊 Loaded $($Users.Count) user(s) from CSV" -ForegroundColor Green

# Connect to Graph
Write-Host "`n🔌 Connecting to Microsoft Graph..." -ForegroundColor Yellow
Connect-MgGraph -Scopes "User.ReadWrite.All", "Directory.ReadWrite.All" | Out-Null
Write-Host "✅ Connected" -ForegroundColor Green

# Try Exchange Online connection
try {
    Write-Host "`n📧 Connecting to Exchange Online..." -ForegroundColor Yellow
    Connect-ExchangeOnline -ShowBanner:$false -ErrorAction Stop
    $ExchangeConnected = $true
    Write-Host "✅ Connected to Exchange Online" -ForegroundColor Green
} catch {
    $ExchangeConnected = $false
    Write-Host "⚠️ Exchange connection failed - mailbox forwarding will be skipped" -ForegroundColor Yellow
}

$successCount = 0
$failCount = 0

foreach ($row in $Users) {
    $userUpn = Trim-OrNull $row.userPrincipalName
    $forwardTo = Trim-OrNull $row.ForwardTo

    if (-not $userUpn) {
        Write-Host "`n⚠️ Skipping row - missing UPN" -ForegroundColor Yellow
        continue
    }

    Write-Host "`n----------------------------------------" -ForegroundColor DarkCyan
    Write-Host "Offboarding: $userUpn" -ForegroundColor Cyan

    # Find the user
    try {
        $user = Get-MgUser -UserId $userUpn -ErrorAction Stop
        Write-Host "✅ User found: $($user.DisplayName)" -ForegroundColor Green
    } catch {
        Write-Host "❌ User not found in Entra ID" -ForegroundColor Red
        $failCount++
        continue
    }

    # 1. Block sign-in
    try {
        Update-MgUser -UserId $user.Id -AccountEnabled:$false -ErrorAction Stop
        Write-Host "✅ Sign-in blocked" -ForegroundColor Green
    } catch {
        Write-Host "❌ Failed to block sign-in: $_" -ForegroundColor Red
    }

    # 2. Revoke all sessions
    try {
        Invoke-MgInvalidateUserRefreshToken -UserId $user.Id -ErrorAction Stop
        Write-Host "✅ All sessions revoked" -ForegroundColor Green
    } catch {
        Write-Host "❌ Failed to revoke sessions: $_" -ForegroundColor Red
    }

    # 3. Remove all licenses
    try {
        $licenses = Get-MgUserLicenseDetail -UserId $user.Id -ErrorAction Stop
        if ($licenses -and $licenses.Count -gt 0) {
            $skuIds = $licenses.SkuId
            Set-MgUserLicense -UserId $user.Id -AddLicenses @() -RemoveLicenses $skuIds -ErrorAction Stop
            Write-Host "✅ All licenses removed ($($skuIds.Count) licenses)" -ForegroundColor Green
        } else {
            Write-Host "ℹ️ No licenses to remove" -ForegroundColor Gray
        }
    } catch {
        Write-Host "❌ Failed to remove licenses: $_" -ForegroundColor Red
    }

    # 4. Set mailbox forwarding (if requested and Exchange connected)
    if ($forwardTo -and $ExchangeConnected) {
        try {
            Set-Mailbox -Identity $userUpn -ForwardingSMTPAddress $forwardTo -DeliverToMailboxAndForward:$false -ErrorAction Stop
            Write-Host "✅ Mailbox forwarding set to: $forwardTo" -ForegroundColor Green
        } catch {
            Write-Host "❌ Failed to set forwarding: $_" -ForegroundColor Red
        }
    } elseif ($forwardTo -and -not $ExchangeConnected) {
        Write-Host "⚠️ Forwarding requested but Exchange not connected - skipping" -ForegroundColor Yellow
    } else {
        Write-Host "ℹ️ No forwarding address provided" -ForegroundColor Gray
    }

    # 5. Mark as ex-staff
    try {
        Update-MgUser -UserId $user.Id -JobTitle "Ex-Staff" -Department "Ex-Staff" -ErrorAction Stop
        Write-Host "✅ User tagged as Ex-Staff" -ForegroundColor Green
    } catch {
        Write-Host "❌ Failed to update job title: $_" -ForegroundColor Red
    }

    $successCount++
    Write-Host "✅ Offboarding completed for $userUpn" -ForegroundColor Green
}

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "OFFBOARDING COMPLETE" -ForegroundColor Cyan
Write-Host "✅ Successful: $successCount" -ForegroundColor Green
Write-Host "❌ Failed: $failCount" -ForegroundColor Red
Write-Host "========================================" -ForegroundColor Cyan