AADdevice-Cleanup

Author(s)

• Jeff Gilbert (@JeffGilb)

Functions

Authenticate write-Log whatIf Disable Delete

Dependencies

This script has no dependencies.

Release Notes

Version 1.0: Original published version.
Version 2.0: Updated to improve Autopilot and Hybrid Azure AD joined device disable/delete behavior as well as logging/reporting improvements.
Version 2.1: Added check for required Azure AD PowerShell module.
Version 2.2: Fixed bug in event logging.
*************************************************************************************************************************
READ ME!
*************************************************************************************************************************
This script is provided on an "as is" without warranties of any kind. USE AT YOUR OWN RISK.
Test in your own environment before using in production. You assume all risk if you run the script.
Review the Authentication function section to determine how you will authenticate with Azure AD. The default configuration
is to interactively log on to Azure AD, but you can modify the script to silently authenticate to leverage the script
in a scheduled task. More information here: https://www.jeffgilb.com/connecting-to-azure-ad-with-powershell/
It is not advisable to immediately delete a device that appears to be stale because you can't undo a deletion in the case
of false positives. As a best practice, disable a device for a grace period before deleting it. In your policy, define a
timeframe to disable a device before deleting it.
If your device is under control of Intune or any other MDM solution, retire the device in the management system before
disabling or deleting it.
Don't delete system-managed devices (i.e. Autopiot registered devices). Once deleted, these devices can't
be reprovisioned. ***This script uses the Get-AzureADDevice cmdlet which excludes system-managed devices by default.***
Hybrid Azure AD joined devices should follow your policies for on-premises stale device management. This script
is used to manage stale Azure AD device accounts and WILL NOT delete Hybrid Azure AD joined devices.
When configured, BitLocker keys for Windows 10 devices are stored on the device object in Azure AD. If you delete a
stale device, you also delete the BitLocker keys that are stored on the device. You should determine whether your
cleanup policy aligns with the actual lifecycle of your device before deleting a stale device.
Need help defining a cleanup policy? Read this article:
https://docs.microsoft.com/azure/active-directory/devices/manage-stale-devices#plan-the-cleanup-of-your-stale-devices
Required parameters: action, days
Optional parameter: whatIf
Device accounts must be disabled in order to be deleted.
CSV reports are created in the public user documents directory.
Application Event Logs are generated when the script runs to disable or delete accounts.
Syntax: AADdevice-Cleanup -action <disable or delete> -days <number of days inactive> -WhatIf (optionally just create a CSV report instead of doing the action)
Examples:
Disable device accounts that have been inactive for 60 days: .\AADdevice-Cleanup -action disable -days 60
Delete device accounts that have been inactive for 90 days: .\AADdevice-Cleanup -action delete -days 90
Create a report of devices that have been inactive 30 days: .\AADdevice-Cleanup -action disable -days 30 -WhatIf
*************************************************************************************************************************