Offboard Obsolete Machines from Microsoft Defender for Endpoint

Microsoft Defender for Endpoint (formerly known as Defender ATP) allows you to onboard and offboard devices using various tools such as Microsoft Endpoint Manager, Group Policies or through a custom script.

This works great when your device is still accessible, however what if the device is no longer managed by your organization’s MEM or other configuration management tool? This happens a lot in BYOD scenarios, where once an employee leaves the organization, they just remove the Azure AD Join association without offboarding the device from Defender.

Ideally, there should be an option to automatically offboard the machines from Defender during the disjoining from Azure AD Process. It may be possible that Microsoft is already working on it, until then you can use this method to remove the offboard the devices from Defender ATP using API.

Let’s get started, it is assumed that you have the required permissions (Global Admin or others) to offboard devices.

Steps to Offboard Obsolete Devices

1. Login to Defender for Endpoint admin center. ( https://securitycenter.windows.com/ ) or the new M365 security center (https://security.microsoft.com)
2. Under devices, find the device you want to offboard. Click on the device name to open the device page.
3. Once you open the device page, you will find a device id in the URL. In below example, the highlighted value is the device ID. Make a note of this device id.

https://securitycenter.windows.com/machines/5e2a880e05a9f035ff5976b19589c21681e02d22/overview or https://security.microsoft.com/machines/v2/ 5e2a880e05a9f035ff5976b19589c21681e02d22

4. Please note that this device id is different than the Azure AD device ID.

5. In Defender admin center, navigate to Partners & API > API Explorer .

6. In the API explorer, change the API call type to Post and enter following URL. Be sure to replace the device id with actual device id copied in previous step.

POST https://api.securitycenter.microsoft.com/api/machines/enterdeviceidhere/offboard

7. In Body area, enter following JSON data.

               {“Comment”: “Offboard machine by automation”}

8.. Click Run Query, if you get a 200 response, the request for offboarding is submitted. In case of any errors, you will see the details in output.

9. It may take few hours (to few days in some cases) for offboarding to complete. If you try to run the API call again, you should see the error message stating that offboarding request already exists.

You can offboard as many devices as you want with this method. You can look at using automation scripts to this programmatically and authenticate using a Service Principal.

That’s it.