Automating Stale Device Cleanup with Graph API

  • Article

We are back with another post today on how you can use Graph API to automate actions in Intune. We hear from a lot of customers that they want to automatically clean up devices that have not checked in with Intune in 90 days. Since Intune is built on top of Graph API, we can automate this pretty easily.

 

Today's Goal: Wipe devices that have not checked in with the service for 90 or more days.

 

Why Should I Automate Device Cleanup?

Well, there is nothing saying that you have to… but if you are anything like us, it is nice to keep our tenant records clean. Sometimes devices stop checking in or are no longer managed, but their record stays around in the Intune console. This can inflate the reported number of devices being managed by Intune, and potentially even cause you to see duplicate records for the same device. Through automating device cleanup, you can run the below script to (1) go through and get a list of all of your devices that have not checked in for 90+ days, and then (2) determine if you want to proceed with retiring all of those devices from the Intune console.

 

How Do I Run This Script?

  1. Download a copy of the script from the TechNet Gallery. You can find it at this link: https://gallery.technet.microsoft.com/Script-to-Remove-Stale-8328aca0 

 

  1. Ensure that rights have been delegated so the service account (if you are not using a Global Admin for this task) has permissions to execute actions via Graph API. We discussed more details on this in a previous blog post. For more detail here about setting up a service account and granting rights for it to execute actions against Graph API: https://blogs.technet.microsoft.com/smeems/2017/12/18/automate-dep-assignment/#delegate

 

  1. Set up your method for authenticating to Graph API. Review the aforementioned blog post for steps to determine how to set up your authentication file: https://blogs.technet.microsoft.com/smeems/2017/12/18/automate-dep-assignment/#set

 

  1. Open the script and search for #update before running. This will allow you to specify your username and the path to the secure password file on your machine. Remember, when you generate the secure password file it is only valid on the machine it was created on. So, you cannot move it to other machines and run the script without creating a new password file.

 

So What Does This Script Do?

The script first returns all of the devices that have not checked in with the Intune service for 90 or more days by calling Graph API. Once we have all of these device records, we ask for admin input on a few items…

 

  1. We first ask if you want to see all of the returned devices right in the PowerShell window formatted as a table. This allows you to quickly view the devices returned, and may be better used if you do not think there are many devices that fit the criteria of not having checked in for 90+ days.
  2. We then ask if you want to export device info to a CSV, that way you can further review the devices that have not checked in within 90 days. When this CSV is created, we check to see if there is a file path at "C:\temp", and if not, we create a folder there and then create the CSV in that location.

***Proceed with caution! Read the below IMPORTANT NOTE before completing step 3***

  1. Finally, we verify that you are indeed ready to start removing these stale devices. When you go forward with this, we first issue a "Retire" command, and then we follow up with a "Delete" command for each device in the returned devices from Graph API.

 

IMPORTANT NOTE:

Once you continue with step 3, there is no going back. The devices that were returned initially will be retired/wiped, meaning they will be removed from Intune. Ensure you are ready to do this. We recommend you review all of the devices returned and make sure that you do indeed want to remove them.

We recommend you run this script manually each time and do not set it up to run in a Scheduled Task. By running it manually you can ensure that nothing is removed that you do not want to remove.

 

The other great thing about Intune being built on top of Graph API is that we have full auditing capabilities. So whenever you run this script, you can then look at the Audit Logs in Intune and see that the devices were retired and deleted. Here is a screenshot of what these logs look like after running the script:

Screenshot of UI in Intune Azure portal of the Intune device audit logs. Shows that an admin initiated delete and retire commands

We capture the date, who initiated the wipe, and what the activity was on the device. The two records in the screenshot above represent the running of this cleanup script and removing a stale device that had not checked in since November of last year. So even though you are executing these actions via PowerShell, you will still have an audit trail.

 

Bringing It All Together

You now have everything you need to download the sample script and remove any stale devices that may be lingering in your tenant. Again, execute this script with caution because it can remove a large number of devices. Review the exportable CSV to ensure that everything being removed from Intune lines up with what you are looking to accomplish. With all of these things in mind, you should be able to clean up your tenant and get rid of those pesky, stale device records!

 

If you are interested in learning more about automation opportunities with Intune, go check out our PowerShell samples on Github: https://github.com/microsoftgraph/powershell-intune-samples

 

The script written today started by downloading a few of these samples and modifying them to achieve our needs. The two base samples used were:

These samples can be very helpful in putting together scripts that will help with your automation opportunities. Looking for guidance on how to automate other Intune actions? Let us know in the comments below.

 

Happy scripting!

 

-Josh and Sarah