M365-006 · Script
Device Inventory and Cleanup
Finds stale Microsoft Entra ID devices and Exchange mobile devices, and optionally disables or removes them.
What it does
Entra ID devices: lists every device with OS, join type, managed and compliant state, and last sign-in. Devices with no sign-in for -StaleDays are stale. Report (default) - report only Disable - disable stale devices that are still enabled Remove - delete stale devices that are already disabled (run Disable first, wait a few weeks, then Remove) Always skipped by Disable and Remove: Windows Autopilot devices (deleting them breaks Autopilot) and hybrid-joined devices (they come back from on-premises sync). With -IncludeMobileDevices, also lists phones and tablets syncing mail through Exchange ActiveSync, flags quarantined or blocked ones, and in Remove mode deletes partnerships that have not synced in -StaleDays.
Requirements
Microsoft Graph PowerShell SDK (and ExchangeOnlineManagement for mobile devices), installed by you from the PowerShell Gallery (not included). Graph application permissions: Device.Read.All (Report) or Device.ReadWrite.All (Disable/Remove) plus the Cloud Device Administrator role for the app. Windows PowerShell 5.1 or PowerShell 7.
How to run it
- Run from: an admin workstation or scheduled task with the Microsoft modules installed and app sign-in configured
- This is an admin script for your Microsoft 365 tenant, not a per-device endpoint script
- User interaction: none with app-only sign-in
- Schedule: run on demand, or weekly for reports
Settings
| Name | What it does | Options | Default |
|---|---|---|---|
| Mode | Report (default), Disable, or Remove. | Report, Disable, Remove | Report |
| StaleDays | Days without sign-in (or sync) before a device is stale. Default: 90. | 90 | |
| IncludeMobileDevices | Also check Exchange ActiveSync mobile devices (needs -Organization or an Exchange session). | False | |
| TenantId | Directory (tenant) ID, for unattended app-only sign-in. | ||
| ClientId | Application (client) ID of your app registration. | ||
| CertificateThumbprint | Thumbprint of the certificate uploaded to the app registration. | ||
| Organization | Your tenant's onmicrosoft.com name (only for -IncludeMobileDevices). | ||
| UseExistingSession | Use Microsoft Graph and Exchange Online sessions you already opened. | False |
Exit codes
- 0 = Completed, no stale or quarantined devices left
- 1 = Stale or quarantined devices found, or an action failed
- 2 = Script error (see log)
Testing steps
- Run it first with the mode set to Report on one test account or small group. Nothing is changed in that mode.
- Read the log and confirm the planned changes are what you expect.
- Run your chosen settings on the same test target and confirm the result.
- Check the exit code: 0 = OK, 1 = needs attention, 2 = error (see log), 9 = this copy is past its Valid until date.
- Roll out to a small group next, then everyone.
Rollback steps
Report mode changes nothing. Disabled devices can be enabled again in the Microsoft Entra admin center. Removed devices must be registered or joined again. Removed mobile partnerships come back when the user syncs again.
Version and change log
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | November 2026 | First release. |