Offboarding devices from Microsoft Defender for Business using an API with PowerShell

I have detailed how you can offboard Windows 10 devices from Microsoft Defender for Endpoint using an Intune policy here:

Offboarding Windows 10 devices from Microsoft Defender for Business

You can also offboard all devices centrally using an API and PowerShell quite easily.

The first thing you’ll need to do is create an Azure AD app in the destination tenant. I’ve covered off how to do this via the web interface here:

https://blog.ciaops.com/2019/04/17/using-interactive-powershell-to-access-the-microsoft-graph/

and using a PowerShell script I wrote here:

https://blog.ciaops.com/2020/04/18/using-the-microsoft-graph-with-multiple-tenants/

You’ll also need to provide this Azure AD app the appropriate permissions in the Defender for Endpoint API to offboard devices (as well as have a license for Defender for Endpoint in your tenant). To see how to set these permissions you can review my previous article:

Using the Defender for Endpoint API and PowerShell

To permit device offboarding you’ll need to provide your Azure AD application with these additional permissions from the Defender API as shown above:

Machine.Offboard

Machine.Read.All

Machine.ReadWrite.All

Don’t also forget to consent to these after you have added them.

In summary, an Azure AD app is used to provide access to the Defender for Endpoint API. This access also requires the appropriate permissions be assigned to that Azure AD app for the Defender for Endpoint API to offboard devices.

When the Azure AD app was initially created the following parameters should have been available:

1. Client (or Application) ID

2. Tenant ID

3. Client (or Application secret)

You’ll need to enter these into the script I have created here:

https://github.com/directorcia/Office365/blob/master/mde-apioffboard.ps1

around line 35:

Ensure your values these are kept secure! I have discussed ways of doing this using the Azure Keyvault or encrypted XML files previously.

After updating the values in the script and running it, the script will firstly get a list of all the devices currently onboarded with Defender for Endpoint.

You should then be presented with a list of devices currently onboarded to Microsoft Defender for Endpoint as shown above. Select the device or devices you wish to offboard. Multiple selections are available here using the CTRL and SHIFT plus select. When the selection is made press the OK button to continue.

The devices selected will then be offboarded via the API. As you can also see above, if a device has already commenced the offboarding process you will receive a warning.

Although using an API to offboard devices is no faster than using an Intune policy or a local script, it still provides a handy centralised approach for offboarding management.

If you also have a look at this article I wrote:

Using the Microsoft Graph with multiple tenants

you’ll probably see how you can easily extend this script so that it enables you to offboard devices from multiple tenants. I have already done this and that premium script is available for CIAOPS Patrons.

Once you have an Azure AD application in place within your tenant with the appropriate permissions, offboarding devices from Microsoft Defender for Endpoint via an API is pretty straight forward. Hopefully, my free script takes care of most of the heavy lifting for you as well making it a simple process to select and offboard devices for Microsoft Defender for Endpoint in any number of tenants you manage.