Managing Windows AutoPilot devices using the Intune Graph API

A while back, I published a sample script called Get-WindowsAutoPilotInfo, which is designed to help define existing computers with the Windows AutoPilot deployment service, See https://blogs.technet.microsoft.com/mniehaus/2017/12/12/gathering-windows-autopilot-hardware-details-from-existing-machines/ for more details about that.

Some people have asked to take this one more step, to automate the process of uploading the gathered hardware details.  Fortunately, this can be done using the Intune Graph API (exactly what the Intune portal uses behind the scenes).  To show you how to do that, I’ve published a sample PowerShell module called WindowsAutoPilotIntune on the PowerShell Gallery.  Here’s an overview of how to use it:

Install the needed modules

There are two modules needed, the WindowsAutoPilotIntune module and the AzureAD module that it uses for authenticating with Intune.  These can both be installed using the Install-Module PowerShell cmdlet:

Install-Module AzureAD
Install-Module WindowsAutoPilotIntune

Here’s what that looks like:

Then we can exercise it a little by getting a list of the devices that have already been uploaded.  First, load the module and connect to Intune by first specifying the user to use:

Import-Module WindowsAutoPilotIntune
Connect-AutoPilotIntune

After specifying the user principal, you’ll be prompted for a password (and if this is the first time you’ve used the Intune Graph APIs, you’ll also be prompted for permission).  Make sure you specify a user that has sufficient rights.  (Note that the authentication will time out after a period of time – the Azure AD sign-in process generates an access token that only has a limited life.)

Then you can get a list of devices:

Get-AutoPilotDevice

So let’s try something a little more involved: Adding some new devices.  I’ll start with a CSV file created with the previously-mentioned Get-WindowsAutoPilotInfo script.  It has five machines in it, one of which have already been imported (to show what an error looks like):

Import-AutoPilotCSV -csvFile C:\Demo.csv

As each device is added to Intune, each new object created in Intune is returned and displayed.  But that doesn’t mean that they are immediately added to the AutoPilot deployment service.  Instead, Intune takes care of this as a background process running asynchronously.  We can check on the progress to see if it is done yet, and once it is done we can see if the devices were added successfully.

The script keeps checking every couple of seconds, and shows you the number of devices that are still being worked on.  It looks like there is no progress being made, but then all complete at the same time (all part of the same batch).  Once all the devices are done, the final status is retrieved and displayed, and as we can see 4 devices were added successfully, while one had a 640 StorageError (which in this case means the device is already registered).

One final step is performed after the final status is retrieved: an object for each device is deleted, leaving just the four new devices, which can be seen with the original Get-AutoPilotDevice cmdlet.

Check out the Import-AutoPilotCSV function to see a few other functions that are used to complete this task:

• Get-AutoPilotImportedDevice, which retrieves the status objects for each device being added.
• Add-AutoPilotImportedDevice, which adds the device.  (Notice that you can specify an order ID for these devices, which could be useful for grouping devices using dynamic Azure AD device groups.)
• Remove-AutoPilotImportedDevice, which removes the status objects once the processing is complete.

Notice that there is no function to remove the added devices.  Just like in the Intune portal, there’s no way to do this yet – you can remove the device via the Microsoft Store for Business, but you’ll still see it in Intune.  That’s still being worked on.

As always, the PowerShell module is provided as an example, provided as-is with no warranty or support, and could easily have bugs. See the Intune Graph API documentation for more details on the REST calls being leveraged, and the PowerShell Intune Samples on GitHub for more on interacting with Intune via the Graph API. 

Let me know via comments on this blog, via Twitter (@mniehaus), or via e-mail (mniehaus@microsoft.com) if you are planning to use this, as we’re interested in understanding the scenarios you might be considering.

Comments

• Anonymous
  April 16, 2018
  I have been looking into this, nice work. But I just want to make people aware that if they have created their own Azure AD App registration for managing intune via graph, this module will not use that App Registration because this module has a hardcoded ClientID ($clientId = "d1ddf0e4-d672-4dae-b554-9d5bdfd93547") Suggestion to this module would be to allow entry of your own AppID as an option and if you leave empty, use default.
  • Anonymous
    April 16, 2018
    This is how you can create your own app registration for more control: http://www.scconfigmgr.com/2017/08/03/create-an-azure-ad-app-registration-for-accessing-microsoft-intune-graph-api-with-powershell/
• Anonymous
  April 30, 2018
  The Remove-AutoPilotImportedDevice cmdlet doesn't seem to work, even after waiting some time. Is removal on a 24 hour schedule then? Removal functionality is necessary especially in the scenario where a non-profit might be inheriting PCs that were once used in a different tenant.