Onboarding nhân viên mới trên Microsoft 365 bằng Microsoft Graph PowerShell: từ file HR đến ngày làm việc đầu tiên

Connect-MgGraph -Scopes "User.Read.All" -NoWelcome
$rows   = Import-Csv ".\hr-onboarding-batch.csv"
$need   = 'GivenName','Surname','EmployeeId','ContractType','Department',
          'JobTitle','City','Country','ManagerEmployeeId','PersonalEmail','StartDate'
$report = foreach ($r in $rows) {
    $issues = @()
    $issues += $need | Where-Object { [string]::IsNullOrWhiteSpace($r.$_) } |
               ForEach-Object { "Thiếu $_" }
    if ($r.ContractType -notin 'Fulltime','Parttime') { $issues += "ContractType không hợp lệ" }
    if (Get-MgUser -Filter "employeeId eq '$($r.EmployeeId)'" -ConsistencyLevel eventual -CountVariable c) {
        $issues += "EmployeeId đã tồn tại" }
    if (-not (Get-MgUser -Filter "employeeId eq '$($r.ManagerEmployeeId)'" -ConsistencyLevel eventual -CountVariable c)) {
        $issues += "Không tìm thấy quản lý" }
    [pscustomobject]@{
        EmployeeId = $r.EmployeeId
        Name       = "$($r.GivenName) $($r.Surname)"
        Status     = if ($issues) { 'NOT READY' } else { 'READY' }
        Issues     = $issues -join '; '
    }
}
$report | Export-Csv ".\onboarding-precheck-report.csv" -NoTypeInformation -Encoding UTF8
$report | Format-Table -AutoSize

function New-UpnCandidate($given, $sur, $domain) {
    $base = ("$given.$sur" -replace '\s','').ToLower()
    $base = $base.Normalize('FormD') -replace '\p{Mn}','' -replace 'đ','d'
    $upn = "$base@$domain"; $i = 1
    while (Get-MgUser -Filter "userPrincipalName eq '$upn'" -ErrorAction SilentlyContinue) {
        $upn = "$base$i@$domain"; $i++ }
    $upn
}
$upn  = New-UpnCandidate $r.GivenName $r.Surname "contoso.com"
$pwd  = -join ((33..126) | Get-Random -Count 32 | ForEach-Object { [char]$_ })
$user = New-MgUser -AccountEnabled -DisplayName "$($r.GivenName) $($r.Surname)" `
    -GivenName $r.GivenName -Surname $r.Surname -UserPrincipalName $upn `
    -MailNickname ($upn.Split('@')[0]) -EmployeeId $r.EmployeeId `
    -EmployeeType $r.ContractType -Department $r.Department -JobTitle $r.JobTitle `
    -City $r.City -UsageLocation $r.Country -OtherMails @($r.PersonalEmail) `
    -EmployeeHireDate ([datetime]$r.StartDate) `
    -PasswordProfile @{ Password = $pwd; ForceChangePasswordNextSignIn = $false }

$mgr = Get-MgUser -Filter "employeeId eq '$($r.ManagerEmployeeId)'" -ConsistencyLevel eventual -CountVariable c
Set-MgUserManagerByRef -UserId $user.Id -BodyParameter @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($mgr.Id)" }

$licGroup = @{ Fulltime = '<GROUP_ID_E3>'; Parttime = '<GROUP_ID_F3>' }
New-MgGroupMember -GroupId $licGroup[$r.ContractType] -DirectoryObjectId $user.Id

Connect-ExchangeOnline -ShowBanner:$false
$deadline = (Get-Date).AddMinutes(20)
do { Start-Sleep 30; $mbx = Get-EXOMailbox -Identity $upn -ErrorAction SilentlyContinue }
until ($mbx -or (Get-Date) -gt $deadline)
if (-not $mbx) { throw "Mailbox của $upn chưa sẵn sàng sau 20 phút" }

if ($r.ContractType -eq 'Fulltime') { Enable-Mailbox -Identity $upn -Archive }
Set-CASMailbox -Identity $upn -PopEnabled $false -ImapEnabled $false -SmtpClientAuthenticationDisabled $true
Set-Mailbox -Identity $upn -RetentionPolicy "Company-Default-Retention"
Set-MailboxRegionalConfiguration -Identity $upn -Language vi-VN -TimeZone "SE Asia Standard Time" -LocalizeDefaultFolderName

Connect-MgGraph -Scopes "UserAuthenticationMethod.ReadWrite.All" -NoWelcome
$start = ([datetime]$r.StartDate).Date.AddHours(8)
$tap = New-MgUserAuthenticationTemporaryAccessPassMethod -UserId $user.Id -BodyParameter @{
    startDateTime     = $start.ToUniversalTime().ToString("o")
    lifetimeInMinutes = 480
    isUsableOnce      = $false }

$body = @"
<p>Chào $($mgr.DisplayName),</p>
<p>Tài khoản cho nhân viên mới <b>$($user.DisplayName)</b> đã sẵn sàng.</p>
<ul><li>Tài khoản: $upn</li>
<li>Temporary Access Pass: <b>$($tap.TemporaryAccessPass)</b></li>
<li>Hiệu lực: $($start.ToString('dd/MM/yyyy HH:mm')), trong 8 tiếng</li></ul>
<p>Vui lòng trao mã trực tiếp cho nhân viên vào ngày đầu tiên.</p>
"@
Send-MgUserMail -UserId "it-onboarding@contoso.com" -BodyParameter @{
    message = @{ subject = "[Onboarding] Tài khoản cho $($user.DisplayName)"
                 body = @{ contentType = "HTML"; content = $body }
                 toRecipients = @(@{ emailAddress = @{ address = $mgr.Mail } }) } }

<#
.SYNOPSIS  Onboarding user Microsoft 365 (Entra ID + Exchange Online) tu file HR.
.EXAMPLE   .\Invoke-M365Onboarding.ps1 -CsvPath .\hr-onboarding-batch.csv -Mode PreCheck
.EXAMPLE   .\Invoke-M365Onboarding.ps1 -CsvPath .\hr-onboarding-batch.csv -Mode Create
#>
[CmdletBinding()]
param(
    [Parameter(Mandatory)] [string]$CsvPath,
    [ValidateSet('PreCheck','Create')] [string]$Mode = 'PreCheck'
)
#region ===== CONFIG =====
$Domain          = "contoso.com"
$SenderMailbox   = "it-onboarding@contoso.com"
$RetentionPolicy = "Company-Default-Retention"
$LicenseGroup    = @{ Fulltime = "<GROUP_ID_E3>"; Parttime = "<GROUP_ID_F3>" }
$TapLifetimeMin  = 480
$MailboxWaitMin  = 20
$OutDir          = Join-Path $PSScriptRoot "output"
#endregion
$ErrorActionPreference = 'Stop'
New-Item -ItemType Directory -Path $OutDir -Force | Out-Null
$Required = 'GivenName','Surname','EmployeeId','ContractType','Department','JobTitle',
            'City','Country','ManagerEmployeeId','PersonalEmail','StartDate'
function Get-UserByEmployeeId([string]$Id) {
    Get-MgUser -Filter "employeeId eq '$Id'" -ConsistencyLevel eventual -CountVariable c `
        -Property Id,DisplayName,Mail,UserPrincipalName,EmployeeId | Select-Object -First 1
}
function New-UpnCandidate([string]$Given, [string]$Sur) {
    $base = ("$Given.$Sur" -replace '\s','').ToLower() -replace 'đ','d'
    $base = ($base.Normalize([Text.NormalizationForm]::FormD) -replace '\p{Mn}','') -replace '[^a-z0-9\.]',''
    $upn = "$base@$Domain"; $i = 1
    while (Get-MgUser -Filter "userPrincipalName eq '$upn'" -ErrorAction SilentlyContinue) {
        $upn = "$base$i@$Domain"; $i++ }
    $upn
}
function New-RandomPassword { -join ((48..57)+(65..90)+(97..122)+(33,35,36,37,64) | Get-Random -Count 32 | ForEach-Object {[char]$_}) }
# ===== CONNECT =====
Connect-MgGraph -NoWelcome -Scopes "User.ReadWrite.All","Group.ReadWrite.All",
    "UserAuthenticationMethod.ReadWrite.All","Mail.Send"
$Rows = Import-Csv $CsvPath
# ===== PRE-CHECK =====
$Check = foreach ($r in $Rows) {
    $issues = @()
    $issues += $Required | Where-Object { [string]::IsNullOrWhiteSpace($r.$_) } | ForEach-Object { "Thieu $_" }
    if ($r.ContractType -notin 'Fulltime','Parttime') { $issues += "ContractType khong hop le" }
    if ($r.EmployeeId -and (Get-UserByEmployeeId $r.EmployeeId)) { $issues += "EmployeeId da ton tai" }
    if ($r.ManagerEmployeeId -and -not (Get-UserByEmployeeId $r.ManagerEmployeeId)) { $issues += "Khong tim thay quan ly" }
    try { [void][datetime]$r.StartDate } catch { $issues += "StartDate sai dinh dang" }
    [pscustomobject]@{ EmployeeId = $r.EmployeeId; Name = "$($r.GivenName) $($r.Surname)"
        Status = if ($issues) {'NOT READY'} else {'READY'}; Issues = $issues -join '; ' }
}
$Check | Export-Csv (Join-Path $OutDir "onboarding-precheck-report.csv") -NoTypeInformation -Encoding UTF8
$Check | Format-Table -AutoSize
if ($Mode -eq 'PreCheck') { return }
# ===== CREATE =====
Connect-ExchangeOnline -ShowBanner:$false
$Ready  = $Rows | Where-Object { $_.EmployeeId -in ($Check | Where-Object Status -eq 'READY').EmployeeId }
$Result = [System.Collections.Generic.List[object]]::new()
foreach ($r in $Ready) {
    $log = [ordered]@{ EmployeeId = $r.EmployeeId; UPN = ''; CreateUser='SKIP'; Manager='SKIP'
        License='SKIP'; Mailbox='SKIP'; MailboxConfig='SKIP'; TAP='SKIP'; Notify='SKIP'; Error='' }
    try {
        # 1. Tao user
        $upn = New-UpnCandidate $r.GivenName $r.Surname
        $log.UPN = $upn
        $user = New-MgUser -AccountEnabled -DisplayName "$($r.GivenName) $($r.Surname)" `
            -GivenName $r.GivenName -Surname $r.Surname -UserPrincipalName $upn `
            -MailNickname ($upn.Split('@')[0]) -EmployeeId $r.EmployeeId -EmployeeType $r.ContractType `
            -Department $r.Department -JobTitle $r.JobTitle -City $r.City -UsageLocation $r.Country `
            -OtherMails @($r.PersonalEmail) -EmployeeHireDate ([datetime]$r.StartDate) `
            -PasswordProfile @{ Password = (New-RandomPassword); ForceChangePasswordNextSignIn = $false }
        $log.CreateUser = 'OK'
        # 2. Gan quan ly
        $mgr = Get-UserByEmployeeId $r.ManagerEmployeeId
        Set-MgUserManagerByRef -UserId $user.Id -BodyParameter @{
            "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($mgr.Id)" }
        $log.Manager = 'OK'
        # 3. License qua group
        New-MgGroupMember -GroupId $LicenseGroup[$r.ContractType] -DirectoryObjectId $user.Id
        $log.License = 'OK'
        # 4. Cho mailbox
        $deadline = (Get-Date).AddMinutes($MailboxWaitMin)
        do { Start-Sleep 30; $mbx = Get-EXOMailbox -Identity $upn -ErrorAction SilentlyContinue }
        until ($mbx -or (Get-Date) -gt $deadline)
        if (-not $mbx) { $log.Mailbox = 'FAIL'; throw "Mailbox chua san sang sau $MailboxWaitMin phut" }
        $log.Mailbox = 'OK'
        # 5. Cau hinh mailbox
        if ($r.ContractType -eq 'Fulltime') { Enable-Mailbox -Identity $upn -Archive | Out-Null }
        Set-CASMailbox -Identity $upn -PopEnabled $false -ImapEnabled $false -SmtpClientAuthenticationDisabled $true
        Set-Mailbox -Identity $upn -RetentionPolicy $RetentionPolicy
        Set-MailboxRegionalConfiguration -Identity $upn -Language vi-VN -TimeZone "SE Asia Standard Time" -LocalizeDefaultFolderName
        $log.MailboxConfig = 'OK'
        # 6. Temporary Access Pass
        $start = ([datetime]$r.StartDate).Date.AddHours(8)
        if ($start -lt (Get-Date)) { $start = Get-Date }
        $tap = New-MgUserAuthenticationTemporaryAccessPassMethod -UserId $user.Id -BodyParameter @{
            startDateTime = $start.ToUniversalTime().ToString("o")
            lifetimeInMinutes = $TapLifetimeMin; isUsableOnce = $false }
        $log.TAP = 'OK'
        # 7. Gui thong tin cho quan ly (khong ghi TAP vao log)
        $body = "<p>Chao $($mgr.DisplayName),</p><p>Tai khoan cho nhan vien moi <b>$($user.DisplayName)</b> da san sang.</p>" +
                "<ul><li>Tai khoan: $upn</li><li>Temporary Access Pass: <b>$($tap.TemporaryAccessPass)</b></li>" +
                "<li>Hieu luc tu: $($start.ToString('dd/MM/yyyy HH:mm')), trong $([int]($TapLifetimeMin/60)) tieng</li></ul>" +
                "<p>Vui long trao ma truc tiep cho nhan vien vao ngay dau tien.</p>"
        Send-MgUserMail -UserId $SenderMailbox -BodyParameter @{ message = @{
            subject = "[Onboarding] Tai khoan cho $($user.DisplayName)"
            body = @{ contentType = "HTML"; content = $body }
            toRecipients = @(@{ emailAddress = @{ address = $mgr.Mail } }) } }
        $log.Notify = 'OK'
        Write-Host "OK  $upn" -ForegroundColor Green
    }
    catch { $log.Error = $_.Exception.Message; Write-Host "ERR $($r.EmployeeId): $($log.Error)" -ForegroundColor Red }
    $Result.Add([pscustomobject]$log)
}
$ResultFile = Join-Path $OutDir ("onboarding-result-{0:yyyyMMdd-HHmm}.csv" -f (Get-Date))
$Result | Export-Csv $ResultFile -NoTypeInformation -Encoding UTF8
$Result | Format-Table EmployeeId,UPN,CreateUser,License,Mailbox,TAP,Notify -AutoSize
Write-Host "DONE -> $ResultFile" -ForegroundColor Cyan