Streamline Your Security: A Step-by-Step Guide to Cleaning Up Orphaned Windows Hello for Business Keys in Azure AD

Safely remove lingering WHfB keys using the WHfBTools PowerShell module to enhance your Azure AD security posture.

Windows Hello for Business (WHfB) enhances authentication security, but when devices are removed from Azure Active Directory (Azure AD), their associated WHfB public keys can sometimes remain in the directory, becoming "orphaned." These orphaned keys, especially if generated on devices with vulnerable Trusted Platform Modules (TPMs), can pose a security risk. This guide provides IT administrators with detailed steps to identify and remove these keys using Microsoft's recommended WHfBTools PowerShell module within an Azure AD environment.

Highlights

Identify & Remove: Learn to use the WHfBTools module to accurately detect and delete orphaned WHfB keys from Azure AD.
Security First: Understand the importance of patching TPM vulnerabilities (like ROCA/CVE-2017-15361) and other security best practices before and during cleanup.
Azure AD Focused: Follow steps specifically tailored for Azure AD joined or hybrid Azure AD joined environments where key management originates in the cloud.

Understanding Orphaned WHfB Keys

An orphaned WHfB key is a public key stored in Azure AD (and potentially synced to on-premises AD in hybrid setups) that belongs to a user-device pairing where the device no longer exists or is inactive in Azure AD. This typically happens during device lifecycle events like decommissioning or replacement.

While Azure AD automatically rejects authentication attempts using these orphaned keys, their presence can still represent a security concern, particularly if the corresponding private key might be compromised due to hardware vulnerabilities (e.g., CVE-2017-15361, also known as ROCA). Regularly cleaning up these keys is a crucial security hygiene practice.

Prerequisites and Preparation

Before you begin the cleanup process, ensure you meet the following requirements and perform preparatory steps:

1. Required Permissions

Azure AD Roles

You need sufficient permissions in Azure AD to query and delete WHfB keys. Assign one of the following roles to the account performing these actions:

Global Administrator
An equivalent custom role with permissions to manage device registration policies and user authentication methods.

Local Permissions

You'll need local administrator rights on the machine where you run PowerShell to install modules and execute scripts.

2. Environment Setup

PowerShell Version

Use a supported version of PowerShell:

Windows PowerShell 5.1 or later
PowerShell 7 or later

PowerShell Execution Policy

Your execution policy must allow running scripts downloaded from the internet (e.g., RemoteSigned). Check your policy with Get-ExecutionPolicy and set it if necessary (run PowerShell as Administrator):

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

Required PowerShell Modules

Ensure you have the necessary modules. The WHfBTools module might depend on the Azure AD PowerShell module (AzureAD). You'll install WHfBTools in the steps below. The AzureAD module is being deprecated; while WHfBTools may currently rely on it, be prepared to potentially switch to Microsoft Graph PowerShell SDK in the future.

3. Security Preparations

Patch Vulnerable TPMs

Crucially, ensure that any devices with TPMs affected by known vulnerabilities like CVE-2017-15361 (ROCA) have their firmware updated before generating new WHfB keys. Refer to Microsoft Security Advisory ADV170012. Cleaning up keys generated by vulnerable TPMs is important, but preventing the creation of new vulnerable keys is paramount.

Clean Up Stale Devices

Microsoft recommends cleaning up stale or inactive device objects in Azure AD before you query for orphaned keys. This can simplify the cleanup process by reducing the number of keys associated with devices that are already known to be out of use.

PowerShell is the primary tool for automating administrative tasks like key cleanup in Azure AD.

Step-by-Step Cleanup Process Using WHfBTools

Follow these steps carefully to identify and remove orphaned WHfB keys from your Azure AD tenant.

Step 1: Install the WHfBTools Module

Open PowerShell as an administrator and install the WHfBTools module directly from the PowerShell Gallery.

# Run PowerShell as Administrator
Install-Module -Name WHfBTools -Scope CurrentUser -Force -AllowClobber

-Scope CurrentUser: Installs the module for the current user only. Use AllUsers if needed system-wide (requires elevation).
-Force: Installs the module even if a previous version exists.
-AllowClobber: Overwrites existing commands if conflicts arise (sometimes necessary).

If prompted to install the NuGet provider or trust the repository (PSGallery), type 'Y' or 'A' and press Enter.

Step 2: Import the Module and Connect to Azure AD

In the same PowerShell session, import the newly installed module and connect to your Azure AD tenant.

# Import the module into the current session
Import-Module WHfBTools

# Connect to Azure AD using an account with required permissions
# Note: The AzureAD module is being deprecated. Future updates might require Connect-MgGraph.
Connect-AzureAD

You will be prompted to authenticate. Sign in with your Azure AD administrator account (Global Admin or equivalent role).

Step 3: Identify WHfB Keys and Export Data

Use the Get-AzureADWHfBKeys cmdlet provided by the module to retrieve all WHfB key information from your tenant and export it to a CSV file for analysis.

# Define a path for the output CSV file
$outputPath = ".\AzureWHfBKeys_$(Get-Date -Format 'yyyyMMddHHmmss').csv"
Write-Host "Exporting WHfB key data to $outputPath..."

# Retrieve keys and export to CSV
Get-AzureADWHfBKeys -Verbose | Export-Csv -Path $outputPath -NoTypeInformation

Write-Host "Export complete. Please review the file: $outputPath"

Get-AzureADWHfBKeys: Queries Azure AD for all registered WHfB keys.
-Verbose: Provides detailed output during execution.
Export-Csv: Saves the output objects into a CSV file.
-NoTypeInformation: Removes the #TYPE information header from the CSV file for easier processing.

The generated CSV file will contain several columns, including UserPrincipalName, DeviceId, KeyId, Orphaned, and RocaVulnerable.

Step 4: Filter for Orphaned (and Vulnerable) Keys

Open the exported CSV file (e.g., in Microsoft Excel or using PowerShell) and filter the data to identify the keys you need to remove. The primary filter is the Orphaned column.

Keys where the Orphaned column value is True are candidates for removal.
You might also want to identify keys marked as RocaVulnerable = True if you are specifically targeting keys affected by that TPM vulnerability, even if not strictly orphaned yet (though patching is the primary remediation for ROCA).

You can use PowerShell to create a new CSV file containing only the keys targeted for removal:

# Define the path to the original export and the new filtered file
$sourceCsvPath = $outputPath # Use the path from the previous step
$filteredCsvPath = ".\OrphanedWHfBKeys_$(Get-Date -Format 'yyyyMMddHHmmss').csv"

# Import the data and filter for Orphaned keys
Write-Host "Filtering for orphaned keys from $sourceCsvPath..."
$orphanedKeysData = Import-Csv -Path $sourceCsvPath | Where-Object { $_.Orphaned -eq 'true' }

# Optional: Further filter for ROCA vulnerable keys if needed
# $orphanedKeysData = $orphanedKeysData | Where-Object { $_.RocaVulnerable -eq 'true' }

# Export the filtered list
if ($orphanedKeysData) {
    $orphanedKeysData | Export-Csv -Path $filteredCsvPath -NoTypeInformation
    Write-Host "Filtered list saved to $filteredCsvPath. Please review this file before proceeding with removal."
} else {
    Write-Host "No orphaned keys found based on the filter criteria."
}

Crucially, review the filtered CSV file (OrphanedWHfBKeys_*.csv) carefully to ensure it only contains keys you intend to delete. Removing active keys can disrupt user sign-in.

Step 5: Remove the Orphaned Keys

Once you have reviewed and confirmed the list of keys in your filtered CSV file, use the Remove-AzureADWHfBKeys cmdlet (note the plural 'Keys') to remove them in bulk from Azure AD.

# Define the path to the filtered CSV containing keys to be removed
$keysToRemoveCsvPath = $filteredCsvPath # Use the path from the previous step

# Verify the file exists and is not empty before proceeding
if (Test-Path $keysToRemoveCsvPath -PathType Leaf) {
    $keysToRemove = Import-Csv -Path $keysToRemoveCsvPath
    if ($keysToRemove.Count -gt 0) {
        Write-Host "Preparing to remove $($keysToRemove.Count) orphaned keys listed in $keysToRemoveCsvPath..."

        # Pipe the imported data directly to the removal cmdlet
        # This command will likely prompt for confirmation for the batch unless -Force is used (use with caution)
        Import-Csv -Path $keysToRemoveCsvPath | Remove-AzureADWHfBKeys -Verbose

        Write-Host "Removal process initiated. Monitor verbose output for status."
    } else {
        Write-Host "The file $keysToRemoveCsvPath is empty. No keys to remove."
    }
} else {
    Write-Host "Filtered key file not found at $keysToRemoveCsvPath. Removal aborted."
}

Import-Csv: Reads the list of keys to be deleted from your filtered file.
Remove-AzureADWHfBKeys: Processes the input objects and attempts to delete each corresponding key from Azure AD.
-Verbose: Shows detailed progress and results for each key removal attempt.
Confirmation: By default, the cmdlet should prompt for confirmation before deleting. You can use -Force to suppress confirmation, but this is generally discouraged in production environments unless you are certain about the list.

For hybrid environments, removals performed in Azure AD will synchronize down to on-premises Active Directory via Azure AD Connect. Removing keys directly from on-premises AD first is not recommended, as they may be rewritten by Azure AD during sync.

Step 6: Verify the Cleanup

After the removal script has finished, it's good practice to verify that the targeted orphaned keys have indeed been removed.

# Re-run the query to check for remaining orphaned keys
Write-Host "Verifying cleanup... Querying for remaining orphaned keys."
$remainingOrphanedKeys = Get-AzureADWHfBKeys | Where-Object { $_.Orphaned -eq 'true' }

if ($remainingOrphanedKeys.Count -eq 0) {
    Write-Host "Verification successful: No orphaned keys found."
} else {
    Write-Host "Verification needed: $($remainingOrphanedKeys.Count) orphaned keys still detected. Further investigation may be required."
    # Optionally, export the remaining keys for review
    # $remainingOrphanedKeys | Export-Csv -Path .\RemainingOrphanedKeys.csv -NoTypeInformation
}

Review the output. Ideally, no orphaned keys should be reported. If some remain, investigate potential issues (e.g., permissions, transient errors, keys becoming orphaned after the initial query).

Visualizing the WHfB Cleanup Workflow

This mindmap illustrates the key stages involved in the orphaned WHfB key cleanup process described above.

mindmap root["WHfB Orphaned Key Cleanup (Azure AD)"] id1["1. Preparation"] id1a["Verify Permissions (Global Admin)"] id1b["Setup PowerShell Environment"] id1c["Patch Vulnerable TPMs (ROCA)"] id1d["Clean Stale Azure AD Devices (Recommended)"] id2["2. Install & Connect"] id2a["Install WHfBTools Module"] id2b["Import WHfBTools Module"] id2c["Connect to Azure AD (Connect-AzureAD)"] id3["3. Identify & Export"] id3a["Run Get-AzureADWHfBKeys"] id3b["Export Results to CSV"] id4["4. Filter Keys"] id4a["Review Exported CSV"] id4b["Filter for 'Orphaned' = 'true'"] id4c["(Optional) Filter for 'RocaVulnerable' = 'true'"] id4d["Create Filtered CSV for Removal"] id4e["CRITICAL: Verify Filtered List"] id5["5. Remove Keys"] id5a["Import Filtered CSV"] id5b["Run Remove-AzureADWHfBKeys"] id5c["Monitor Verbose Output"] id5d["Handle Confirmations (Avoid -Force unless certain)"] id6["6. Verify Cleanup"] id6a["Re-run Get-AzureADWHfBKeys"] id6b["Filter for 'Orphaned' = 'true'"] id6c["Confirm Zero Orphaned Keys Remain"] id6d["Investigate Remaining Keys if Any"]

Key WHfBTools Cmdlets Summary

This table summarizes the primary PowerShell cmdlets from the WHfBTools and related modules used in this guide:

Cmdlet	Module	Function
`Install-Module`	PowerShellGet	Installs modules from the PowerShell Gallery (used for WHfBTools).
`Import-Module`	PowerShell Core	Loads a module into the current PowerShell session (used for WHfBTools).
`Connect-AzureAD`	AzureAD	Connects the PowerShell session to Azure Active Directory. (Note: Deprecation planned).
`Get-AzureADWHfBKeys`	WHfBTools	Retrieves Windows Hello for Business key information from Azure AD.
`Remove-AzureADWHfBKeys`	WHfBTools	Removes WHfB keys from Azure AD, typically taking input from a CSV or pipeline.
`Where-Object`	PowerShell Core	Filters objects based on property values (used to filter keys based on 'Orphaned' status).
`Export-Csv`	Microsoft.PowerShell.Utility	Exports PowerShell objects into a comma-separated values (CSV) file.
`Import-Csv`	Microsoft.PowerShell.Utility	Imports data from a CSV file into PowerShell objects.

Comparing Aspects of WHfB Key Management

Managing WHfB involves various considerations. This chart provides a conceptual comparison of different aspects relevant to the cleanup process and overall WHfB health, based on administrative opinion and best practices rather than hard data.

This visualization highlights that while automating cleanup has high potential, the manual process carries risks, and the security impact of orphaned keys, especially those tied to vulnerable TPMs, is significant.

Security Considerations and Best Practices

Test Thoroughly: Before running removal scripts in your production environment, test the entire process in a non-production or pilot tenant if possible.
Backup Key Data: Always back up the exported CSV file containing all key information before starting the removal process. Keep the filtered list of removed keys for auditing purposes.
Review Before Deleting: Double-check the filtered list of keys marked for deletion. Ensure no active, valid keys are accidentally included. Removing a necessary key will force the user to re-register for WHfB.
Use Least Privilege: Perform these actions using an account that has the necessary permissions but avoid using highly privileged accounts for routine tasks where possible. Consider Just-In-Time (JIT) access.
Schedule Maintenance Window: Perform bulk key removals during planned maintenance windows to minimize potential impact on users, although removing orphaned keys *should* not affect active users.
Enable Logging: Ensure Azure AD audit logs and PowerShell transcript logging are enabled to record the actions taken.
Regular Cleanup Schedule: Implement a regular schedule (e.g., quarterly or semi-annually) for auditing and cleaning up orphaned WHfB keys as part of your identity lifecycle management procedures.
Patch Management: Continuously monitor for and apply TPM firmware updates to mitigate hardware vulnerabilities that could affect WHfB key security.

Frequently Asked Questions (FAQ)

What exactly is an orphaned Windows Hello for Business key? +

Why is it important to remove these orphaned keys? +

What happens if I accidentally remove a key that isn't orphaned? +

Does removing keys in Azure AD affect my on-premises Active Directory? +

Can I automate this cleanup process? +

References

Using WHfBTools PowerShell module for cleaning up orphaned Windows Hello for Business keys - Microsoft Support
WHfBTools Module - PowerShell Gallery
Microsoft Warns of Windows Hello for Business Orphaned Key Risks - BleepingComputer
Microsoft Warns of Persistent Windows Hello for Business Orphaned Keys - SecurityWeek
Vulnerability in TPM could allow security feature bypass (ADV170012) - Microsoft Security Response Center
Using WHfBTools PowerShell module for cleaning up orphaned Windows Hello for Business keys (KB4533501 Mirror) - PKI Solutions