|
| 1 | +# Remove MFA Authentication Methods for Users |
| 2 | + |
| 3 | +## Summary |
| 4 | + |
| 5 | +This script removes all MFA (Multi-Factor Authentication) methods from user accounts in a Microsoft 365 tenant using Microsoft Graph PowerShell. It supports removing **phone**, **Microsoft Authenticator app**, and **software OATH token** methods. |
| 6 | + |
| 7 | +The script supports two modes: |
| 8 | + |
| 9 | +- **All users mode** — removes MFA for every user in the tenant except those in the exclusion list |
| 10 | +- **Targeted mode** — removes MFA for specific users only by passing `-TargetUsers` |
| 11 | + |
| 12 | +In both modes, accounts in `-ExcludedUsers` (e.g. admin or break-glass accounts) are always protected. |
| 13 | + |
| 14 | +> [!WARNING] |
| 15 | +> Please be aware this script contains commands that will **remove MFA authentication methods** for users in bulk. This is a **destructive and irreversible operation**. Ensure you test in a non-production environment first, and always exclude your admin and other temporary accounts. |
| 16 | +
|
| 17 | + |
| 18 | + |
| 19 | +## Compatibility |
| 20 | + |
| 21 | +| Tool | Version | |
| 22 | +|------|---------| |
| 23 | +| Microsoft Graph PowerShell | v2.x+ | |
| 24 | + |
| 25 | +## Prerequisites |
| 26 | + |
| 27 | +The signed-in account must have the following Graph API permissions: |
| 28 | + |
| 29 | +| Permission | Type | |
| 30 | +|---|---| |
| 31 | +| `UserAuthenticationMethod.ReadWrite.All` | Delegated | |
| 32 | +| `User.Read.All` | Delegated | |
| 33 | + |
| 34 | +```powershell |
| 35 | +# Install required sub-modules if not already installed |
| 36 | +Install-Module Microsoft.Graph.Authentication -Scope CurrentUser -Repository PSGallery -Force |
| 37 | +Install-Module Microsoft.Graph.Users -Scope CurrentUser -Repository PSGallery -Force |
| 38 | +Install-Module Microsoft.Graph.Identity.SignIns -Scope CurrentUser -Repository PSGallery -Force |
| 39 | +``` |
| 40 | + |
| 41 | +> [!NOTE] |
| 42 | +> Install only the three sub-modules listed above rather than the full `Microsoft.Graph` bundle. |
| 43 | +
|
| 44 | +## Script |
| 45 | + |
| 46 | +# [Microsoft Graph PowerShell](#tab/graphps) |
| 47 | + |
| 48 | +```powershell |
| 49 | +#Requires -Modules Microsoft.Graph.Authentication, Microsoft.Graph.Users, Microsoft.Graph.Identity.SignIns |
| 50 | +
|
| 51 | +<# |
| 52 | +.SYNOPSIS |
| 53 | + Removes MFA authentication methods for all users in a tenant using Microsoft Graph PowerShell. |
| 54 | +
|
| 55 | +.DESCRIPTION |
| 56 | + This script connects to Microsoft Graph and removes multi-factor authentication (MFA) methods |
| 57 | + for all users in the tenant, with the ability to exclude specific accounts (e.g., break-glass |
| 58 | + or admin accounts). It handles phone, Microsoft Authenticator app, and software OATH token methods. |
| 59 | +
|
| 60 | + You can optionally target specific users only using -TargetUsers. If not specified, all users |
| 61 | + (except excluded ones) will be processed. |
| 62 | +
|
| 63 | +.PARAMETER ExcludedUsers |
| 64 | + An array of User Principal Names (UPNs) to exclude from MFA removal. |
| 65 | + Typically used to protect admin or break-glass accounts. |
| 66 | + These are always excluded regardless of whether -TargetUsers is used. |
| 67 | +
|
| 68 | +.PARAMETER TargetUsers |
| 69 | + An optional array of User Principal Names (UPNs) to target specifically. |
| 70 | + If provided, only these users will have their MFA methods removed (excluding any in ExcludedUsers). |
| 71 | + If not provided, ALL users in the tenant will be processed (except ExcludedUsers). |
| 72 | +
|
| 73 | +.EXAMPLE |
| 74 | + .\RemoveMFA.ps1 |
| 75 | + Removes MFA methods from ALL users except the excluded accounts. |
| 76 | +
|
| 77 | +.EXAMPLE |
| 78 | + .\RemoveMFA.ps1 -TargetUsers @("john@contoso.onmicrosoft.com", "jane@contoso.onmicrosoft.com") |
| 79 | + Removes MFA methods for specific users only. |
| 80 | +
|
| 81 | +.EXAMPLE |
| 82 | + .\RemoveMFA.ps1 -ExcludedUsers @("admin@contoso.onmicrosoft.com", "breakglass@contoso.onmicrosoft.com") |
| 83 | + Removes MFA methods from ALL users except the specified excluded accounts. |
| 84 | +#> |
| 85 | +
|
| 86 | +[CmdletBinding(SupportsShouldProcess)] |
| 87 | +param ( |
| 88 | + [Parameter(Mandatory = $false)] |
| 89 | + [string[]]$ExcludedUsers = @( |
| 90 | + "admin@contoso.onmicrosoft.com" |
| 91 | + # "breakglass@contoso.onmicrosoft.com" |
| 92 | + ), |
| 93 | +
|
| 94 | + [Parameter(Mandatory = $false)] |
| 95 | + [string[]]$TargetUsers = @() |
| 96 | +) |
| 97 | +
|
| 98 | +# --------------------------------------------------------------------------- |
| 99 | +# Install module if needed (uncomment the line below on first run) |
| 100 | +# Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force |
| 101 | +# --------------------------------------------------------------------------- |
| 102 | +
|
| 103 | +# Connect to Microsoft Graph with required scopes |
| 104 | +Connect-MgGraph -Scopes "UserAuthenticationMethod.ReadWrite.All", "User.Read.All" -NoWelcome |
| 105 | +
|
| 106 | +Write-Host "============================================" -ForegroundColor Cyan |
| 107 | +Write-Host " Remove MFA Methods - Microsoft Graph" -ForegroundColor Cyan |
| 108 | +Write-Host "============================================" -ForegroundColor Cyan |
| 109 | +Write-Host "" |
| 110 | +Write-Host "Excluded accounts:" -ForegroundColor Yellow |
| 111 | +$ExcludedUsers | ForEach-Object { Write-Host " - $_" -ForegroundColor Yellow } |
| 112 | +Write-Host "" |
| 113 | +
|
| 114 | +# --------------------------------------------------------------------------- |
| 115 | +# Determine which users to process: |
| 116 | +# -TargetUsers provided -> process only those specific users |
| 117 | +# -TargetUsers not provided -> process ALL users except ExcludedUsers |
| 118 | +# --------------------------------------------------------------------------- |
| 119 | +if ($TargetUsers.Count -gt 0) { |
| 120 | +
|
| 121 | + Write-Host "Mode: Targeted - processing specified users only." -ForegroundColor Magenta |
| 122 | + Write-Host "" |
| 123 | +
|
| 124 | + $users = [System.Collections.Generic.List[object]]::new() |
| 125 | +
|
| 126 | + foreach ($upn in $TargetUsers) { |
| 127 | + if ($upn -in $ExcludedUsers) { |
| 128 | + Write-Host "Skipping excluded account: $upn" -ForegroundColor Yellow |
| 129 | + continue |
| 130 | + } |
| 131 | + $user = Get-MgUser -UserId $upn -Property Id, UserPrincipalName, DisplayName -ErrorAction SilentlyContinue |
| 132 | + if ($null -eq $user) { |
| 133 | + Write-Host "WARNING: User not found - $upn" -ForegroundColor Red |
| 134 | + } |
| 135 | + else { |
| 136 | + $users.Add($user) |
| 137 | + } |
| 138 | + } |
| 139 | +
|
| 140 | +} |
| 141 | +else { |
| 142 | +
|
| 143 | + Write-Host "Mode: All users - processing entire tenant (except excluded accounts)." -ForegroundColor Magenta |
| 144 | + Write-Host "" |
| 145 | +
|
| 146 | + Write-Host "Retrieving users from tenant..." -ForegroundColor Cyan |
| 147 | + $users = Get-MgUser -All -Property Id, UserPrincipalName, DisplayName | |
| 148 | + Where-Object { $_.UserPrincipalName -notin $ExcludedUsers } |
| 149 | +
|
| 150 | +} |
| 151 | +
|
| 152 | +Write-Host "Found $($users.Count) user(s) to process." -ForegroundColor Cyan |
| 153 | +Write-Host "" |
| 154 | +
|
| 155 | +$totalRemoved = 0 |
| 156 | +$totalErrors = 0 |
| 157 | +
|
| 158 | +foreach ($user in $users) { |
| 159 | +
|
| 160 | + Write-Host "Processing: $($user.DisplayName) ($($user.UserPrincipalName))" -ForegroundColor White |
| 161 | +
|
| 162 | + try { |
| 163 | + # Retrieve all authentication methods for the user |
| 164 | + $authMethods = Get-MgUserAuthenticationMethod -UserId $user.Id -ErrorAction Stop |
| 165 | +
|
| 166 | + if ($authMethods.Count -eq 0) { |
| 167 | + Write-Host " No authentication methods found." -ForegroundColor Gray |
| 168 | + continue |
| 169 | + } |
| 170 | +
|
| 171 | + foreach ($method in $authMethods) { |
| 172 | +
|
| 173 | + $odataType = $method.AdditionalProperties["@odata.type"] |
| 174 | +
|
| 175 | + switch ($odataType) { |
| 176 | +
|
| 177 | + "#microsoft.graph.phoneAuthenticationMethod" { |
| 178 | + if ($PSCmdlet.ShouldProcess($user.UserPrincipalName, "Remove phone authentication method")) { |
| 179 | + Remove-MgUserAuthenticationPhoneMethod ` |
| 180 | + -UserId $user.Id ` |
| 181 | + -PhoneAuthenticationMethodId $method.Id ` |
| 182 | + -ErrorAction Stop |
| 183 | + Write-Host " Removed: Phone authentication method" -ForegroundColor Green |
| 184 | + $totalRemoved++ |
| 185 | + } |
| 186 | + } |
| 187 | +
|
| 188 | + "#microsoft.graph.microsoftAuthenticatorAuthenticationMethod" { |
| 189 | + if ($PSCmdlet.ShouldProcess($user.UserPrincipalName, "Remove Microsoft Authenticator method")) { |
| 190 | + Remove-MgUserAuthenticationMicrosoftAuthenticatorMethod ` |
| 191 | + -UserId $user.Id ` |
| 192 | + -MicrosoftAuthenticatorAuthenticationMethodId $method.Id ` |
| 193 | + -ErrorAction Stop |
| 194 | + Write-Host " Removed: Microsoft Authenticator app" -ForegroundColor Green |
| 195 | + $totalRemoved++ |
| 196 | + } |
| 197 | + } |
| 198 | +
|
| 199 | + "#microsoft.graph.softwareOathAuthenticationMethod" { |
| 200 | + if ($PSCmdlet.ShouldProcess($user.UserPrincipalName, "Remove software OATH token method")) { |
| 201 | + Remove-MgUserAuthenticationSoftwareOathMethod ` |
| 202 | + -UserId $user.Id ` |
| 203 | + -SoftwareOathAuthenticationMethodId $method.Id ` |
| 204 | + -ErrorAction Stop |
| 205 | + Write-Host " Removed: Software OATH token" -ForegroundColor Green |
| 206 | + $totalRemoved++ |
| 207 | + } |
| 208 | + } |
| 209 | +
|
| 210 | + default { |
| 211 | + # Password methods and other built-in methods cannot be removed |
| 212 | + Write-Host " Skipped: $odataType (not removable via API)" -ForegroundColor Gray |
| 213 | + } |
| 214 | + } |
| 215 | + } |
| 216 | + } |
| 217 | + catch { |
| 218 | + Write-Host " ERROR: $($_.Exception.Message)" -ForegroundColor Red |
| 219 | + $totalErrors++ |
| 220 | + } |
| 221 | +} |
| 222 | +
|
| 223 | +Write-Host "" |
| 224 | +Write-Host "============================================" -ForegroundColor Cyan |
| 225 | +Write-Host " Summary" -ForegroundColor Cyan |
| 226 | +Write-Host "============================================" -ForegroundColor Cyan |
| 227 | +Write-Host " Methods removed : $totalRemoved" -ForegroundColor Green |
| 228 | +Write-Host " Errors : $totalErrors" -ForegroundColor $(if ($totalErrors -gt 0) { "Red" } else { "Green" }) |
| 229 | +Write-Host "" |
| 230 | +
|
| 231 | +# Disconnect from Microsoft Graph |
| 232 | +Disconnect-MgGraph |
| 233 | +Write-Host "Disconnected from Microsoft Graph." -ForegroundColor Cyan |
| 234 | +``` |
| 235 | + |
| 236 | +[!INCLUDE [Check out the Microsoft Graph PowerShell SDK to learn more at:](../../docfx/includes/MORE-GRAPHSDK.md)] |
| 237 | +*** |
| 238 | + |
| 239 | +--- |
| 240 | + |
| 241 | +## Contributors |
| 242 | + |
| 243 | +| Author(s) | |
| 244 | +|-----------| |
| 245 | +| [Nirav Raval](https://github.com/nirav-raval) | |
| 246 | + |
| 247 | +## Version history |
| 248 | + |
| 249 | +| Version | Date | Comments | |
| 250 | +|---------|------|----------| |
| 251 | +| 1.0 | Feb 28, 2026 | Initial release | |
| 252 | + |
| 253 | + |
| 254 | +[!INCLUDE [DISCLAIMER](../../docfx/includes/DISCLAIMER.md)] |
| 255 | +<img src="https://m365-visitor-stats.azurewebsites.net/script-samples/scripts/entra-remove-user-mfa-methods" aria-hidden="true" /> |
0 commit comments