Using WHfBTools PowerShell module for cleaning up orphaned Windows Hello for Business Keys

Applies to: Windows Server 2019, all versionsWindows Server 2016

Summary

To help customers identify orphaned Windows Hello for Business (WHfB) keys affected by a TPM vulnerability, Microsoft has published a PowerShell module that can be run by administrators. This article explains how to address the issue described in ADV190026 | “Microsoft Guidance for cleaning up orphaned keys generated on vulnerable TPMs and used for Windows Hello for Business.”

Important Note Before using WHfBTools to remove orphaned keys, the guidance in ADV170012 should be followed to update the firmware of any vulnerable TPMs. If this guidance is not followed, any new WHfB keys generated on a device with firmware that has not been updated will still be affected by CVE-2017-15361 (ROCA).

How to install the WHfBTools PowerShell Module

Install the module by running the following commands:

Installing WHfBTools PowerShell module

Install via PowerShell

PS> Install-Module WHfBTools

PS> # Save the current execution policy so it can be reset later

PS> $SaveExecutionPolicy = Get-ExecutionPolicy

PS> Set-ExecutionPolicy RemoteSigned -Scope Currentuser

PS> Import-Module WHfBTools

Or Install using a download from PowerShell Gallery

  1. Go to https://www.powershellgallery.com/packages/WHfBTools
  2. Download the raw .nupkg file to a local folder and rename with the .zip extension
  3. Extract the contents to a local folder, for example C:\ADV190026

 

Start PowerShell, copy and run the following commands:

PS> # Save the current execution policy so it can be reset later

PS> $SaveExecutionPolicy = Get-ExecutionPolicy

PS> Set-ExecutionPolicy RemoteSigned -Scope Currentuser

PS> CD C:\ADV190026\WHfBTools

PS> Import-Module .\WHfBTools.psd1

 

Install dependencies for using the module:

Installing dependencies for using the WHfBTools module

If you are querying Azure Active Directory for orphaned keys, install the MSAL.PS PowerShell module

Install via PowerShell

PS> Install-Module -Name MSAL.PS -RequiredVersion 4.5.1.1

PS> Import-Module MSAL.PS

Or install using a download from PowerShell Gallery

  1. Go to https://www.powershellgallery.com/packages/MSAL.PS/4.5.1.1
  2. Download the raw .nupkg file to a local folder and rename with the .zip extension
  3. Extract the contents to a local folder, for example C:\MSAL.PS

Start PowerShell, copy and run the following commands:

PS> CD C:\MSAL.PS

PS> Import-Module .\MSAL.PS.psd1

If you are querying Active Directory for orphaned keys, install the Remote Server Administrator Tools (RSAT): Active Directory Domain Services and Lightweight Directory Services Tools

Install via Settings (Windows 10, version 1809 or later)

  1. Go to Settings -> Apps -> Optional Features -> Add a feature
  2. Select RSAT: Active Directory Domain Services and Lightweight Directory Services Tools
  3. Select Install

Or Install via PowerShell

PS> dism /online /Add-Capability /CapabilityName:Rsat.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0

Or install via download

  1. Go to https://www.microsoft.com/en-us/download/details.aspx?id=45520 (Windows 10 Link)
  2. Download the Remote Server Administration Tools for Windows 10 Installer
  3. Launch the Installer once the download is complete

 

Run the WHfBTools PowerShell Module

If your environment has Azure Active Directory joined or hybrid Azure Active Directory joined devices, follow the Azure Active Directory steps to identify and remove keys. The key removals in Azure will sync to Active Directory through Azure AD Connect.

If your environment is on-premises only, follow the Active Directory steps to identify and remove keys.

Querying for orphaned keys and keys affected by CVE-2017-15361 (ROCA)

Query for keys in Azure Active Directory using the following command:

PS> Get-AzureADWHfBKeys -Logging -Report -Tenant contoso.com -All | Export-Csv C:\AzureKeys.csv

This command will query the “contoso.com” tenant for all registered Windows Hello for Business public keys and will output that information to C:\AzureKeys.csv. Replace contoso.com with your tenant name to query your tenant.

The Csv output, AzureKeys.csv, will contain the following information for each key:

  • User Principal Name
  • Tenant
  • Usage
  • Key ID
  • Creation Time
  • Orphaned Status
  • Supports Notify Status
  • ROCA Vulnerability Status

Get-AzureADWHfBKeys will also output a summary of the keys that were queried. This summary provides the following information:

  • Number of users scanned
  • Number of keys scanned
  • Number of users with keys
  • Number of ROCA vulnerable keys

Note There may be stale devices in your Azure AD tenant with Windows Hello for Business keys associated with them. These keys will not be reported as orphaned even though those devices are not being actively used. We recommend following How To: Manage stale devices in Azure AD to clean up stale devices before querying for orphaned keys.

 

Query for keys in Active Directory using the following command:

PS> Get-ADWHfBKeys -Logging -Report -Domain contoso | Export-Csv C:\ADKeys.csv

This command will query the “contoso” domain for all registered Windows Hello for Business public keys and will output that information to C:\ADKeys.csv. Replace contoso with your domain name to query your domain.

The Csv output, ADKeys.csv, will contain the following information for each key:

  • User Domain
  • User SAM Account Name
  • User Distinguished Name
  • Key Version
  • Key ID
  • Creation Time
  • Key Material
  • Key Source
  • Key Usage
  • Key Device ID
  • Approximate Last Logon Timestamp
  • Creation time
  • Custom Key Information
  • KeyLinkTargetDN
  • Orphaned Status
  • ROCA Vulnerability Status
  • KeyRawLDAPValue

Get-ADWHfBKeys will also output a summary of the keys that were queried. This summary provides the following information:

  • Number of users scanned
  • Number of users with keys
  • Number of keys scanned
  • Number of ROCA vulnerable keys
  • Number of orphaned keys (if -SkipCheckForOrphanedKeys not specified)

Note: If you have a hybrid environment with Azure AD joined devices and run “Get-ADWHfBKeys” in your on-premises domain, the number of orphaned keys may not be accurate. This is because Azure AD joined devices are not present in Active Directory and keys associated with Azure AD joined devices may show up as orphaned.

 

Remove orphaned, ROCA vulnerable keys from the directory

Remove keys in Azure Active Directory using the following steps:

  1. Filter the Orphaned and RocaVulnerable columns of AzureKeys.csv to true
  2. Copy the filtered results to a new file, C:\ROCAKeys.csv
  3. Run the following command to delete keys:

PS> Import-Csv C:\ROCAKeys.csv | Remove-AzureADWHfBKey -Tenant contoso.com -Logging

This command imports the list of orphaned, ROCA vulnerable keys and removes them from the contoso.com tenant. Replace contoso.com with your tenant name to remove keys from your tenant.

Note If you delete ROCA vulnerable WHfB keys that are not orphaned yet, it will cause disruption to your users. You should ensure that these keys are orphaned before removing them from the directory.

 

Remove keys in Active Directory using the following steps:

Note Removing orphaned keys from Active Directory in hybrid environments will result in the keys being recreated as part of the Azure AD Connect sync process. If you are in a hybrid environment, remove keys only from Azure AD

  1. Filter the OrphanedKey and ROCAVulnerable columns of ADKeys.csv to true
  2. Copy the filtered results to a new file, C:\ROCAKeys.csv
  3. Run the following command to delete keys:

PS> Import-Csv C:\ROCAKeys.csv | Remove-ADWHfBKey -Logging

This command imports the list of orphaned, ROCA vulnerable keys and removes them from your domain. 

Note If you delete ROCA vulnerable WHfB keys that are not orphaned yet, it will cause disruption to your users. You should ensure that these keys are orphaned before removing them from the directory.