Mastering Usage Location: Syncing On-Premises Active Directory Countries to Microsoft Entra ID

try {
    # Ensure required module is available
    if (-not (Get-Module -ListAvailable -Name Microsoft.Graph.Users)) {
        throw "Required module 'Microsoft.Graph.Users' is not installed. Run: Install-Module Microsoft.Graph -Scope CurrentUser"
    }

    # Connect with the required read scope (uses existing context if already connected with sufficient scope)
    $context = Get-MgContext
    if (-not $context -or ($context.Scopes -notcontains "User.Read.All")) {
        Connect-MgGraph -Scopes "User.Read.All" -NoWelcome -ErrorAction Stop
        $context = Get-MgContext
    }

    if (-not $context -or ($context.Scopes -notcontains "User.Read.All")) {
        throw "Unable to establish a Microsoft Graph session with the required 'User.Read.All' scope."
    }

    # Audit enabled users with a missing usageLocation attribute
    $usersMissingLocation = Get-MgUser -Filter "usageLocation eq null and accountEnabled eq true" `
        -ConsistencyLevel eventual -CountVariable userCount `
        -Property "displayName,userPrincipalName,usageLocation" `
        -All `
        -ErrorAction Stop |
        Select-Object DisplayName, UserPrincipalName, UsageLocation

    if (-not $usersMissingLocation) {
        Write-Output "No enabled users found with a missing usageLocation attribute."
    }
    else {
        $count = @($usersMissingLocation).Count
        Write-Output "Found $count enabled user(s) with a missing usageLocation attribute:"
        $usersMissingLocation
    }
}
catch {
    Write-Error "Failed to audit users for missing usageLocation: $($_.Exception.Message)"
}🐛 Debug / Fix

# Interim bulk remediation: set usageLocation for a specific regional OU/value
# Requires the ActiveDirectory module (RSAT) and Microsoft.Graph.Users

function Invoke-BulkUsageLocationRemediation {
    [CmdletBinding()]
    param(
        [string]$CountryCode = "US"
    )

    try {
        # Ensure ActiveDirectory module (RSAT) is available
        if (-not (Get-Module -ListAvailable -Name ActiveDirectory)) {
            Write-Error "Required module 'ActiveDirectory' is not installed. Install RSAT with: Add-WindowsCapability -Online -Name 'Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0'"
            return
        }
        Import-Module ActiveDirectory -ErrorAction Stop

        # Ensure Microsoft.Graph.Users module is available
        if (-not (Get-Module -ListAvailable -Name Microsoft.Graph.Users)) {
            Write-Error "Required module 'Microsoft.Graph.Users' is not installed. Run: Install-Module Microsoft.Graph -Scope CurrentUser"
            return
        }
        Import-Module Microsoft.Graph.Users -ErrorAction Stop

        # Connect with the required write scope, avoiding WAM interactive issues in headless/embedded terminals
        $context = Get-MgContext
        if (-not $context -or ($context.Scopes -notcontains "User.ReadWrite.All")) {
            Connect-MgGraph -Scopes "User.ReadWrite.All" -UseDeviceCode -NoWelcome -ErrorAction Stop
            $context = Get-MgContext
        }

        if (-not $context -or ($context.Scopes -notcontains "User.ReadWrite.All")) {
            throw "Unable to establish a Microsoft Graph session with the required 'User.ReadWrite.All' scope."
        }

        # Retrieve on-prem AD users in the target region (country code parameterized)
        $users = Get-ADUser -Filter "c -eq '$CountryCode'" -Properties c, UserPrincipalName -ErrorAction Stop

        if (-not $users) {
            Write-Output "No on-premises AD users found matching country code '$CountryCode'."
            return
        }

        foreach ($user in $users) {
            if ([string]::IsNullOrWhiteSpace($user.UserPrincipalName)) {
                Write-Warning "Skipping user '$($user.SamAccountName)': missing UserPrincipalName."
                continue
            }

            try {
                Update-MgUser -UserId $user.UserPrincipalName -UsageLocation $CountryCode -ErrorAction Stop
                Write-Output "Updated usageLocation for $($user.UserPrincipalName)."
            }
            catch {
                Write-Error "Failed to update $($user.UserPrincipalName): $($_.Exception.Message)"
            }
        }
    }
    catch {
        Write-Error "Bulk remediation failed: $($_.Exception.Message)"
    }
}

Invoke-BulkUsageLocationRemediation -CountryCode "US"