Azure Active Directory

Simplify the process of generating an AAD bulk enrollment provisioning package

The process is supposed to be fairly easy: Launch Windows Imaging and Configuration Designer (ICD), walk through the wizard, specify that you want to join Azure AD, type in your Azure AD credentials, generate a provisioning package that can be used on multiple machines to join them to Azure AD. But then reality hits you. Too often, ICD just doesn’t work. It will fail either before prompting for Azure AD credentials, or it will fail after you put in your credentials. And the error is pretty useless: “Bulk token retrieval failed.”

It also makes it challenging to specify a date 180 days out (the maximum duration of a bulk enrollment token) as the UI will only let you select a date 90 days out. If you want something else, you have to calculate and type in the date yourself (and hope it works, might still fail randomly).

Fortunately, there is another option. Through his reverse-engineering of the process, Dr. Nestori Syynimaa (@DrAzureAD on Twitter) has created a PowerShell module, AADInternals, that can do the same thing (and lots of other interesting things — definitely worth checking out). This module is published to the PowerShell Gallery, so it’s easy to install and use.

When it comes to the specifics of the bulk enrollment tokens, there is a blog post that explains the whole process. Interestingly, a Microsoft support post talks about using this AADInternals module to help with this, and there are other posts on the Microsoft forums that point to this point as a workaround for the ICD challenges. But this post still requires that you take the output from the AADInternals PowerShell cmdlets and paste them into the ICD user interface — yes, that helps because it avoids the ICD wizard, but it is still a manual step. And since these bulk enrollment tokens are good for a maximum of 180 days, you have to do this periodically. So what can we do to further automate the process?

Fortunately, there is a mechanism that can be used to generate a provisioning package from the command line using ICD.EXE. All you need is an XML file that describes what should be in the provisioning package (in this case, just the bulk enrollment token, a.k.a. BPRT). So, we can wrap all of this into a single PowerShell script.

Walking through that, here are the steps performed:

  1. Install and load the AADInternals (and NuGet, needed to access the PowerShell Gallery) module.
  2. Authenticate to Azure AD using an account with appropriate rights to the tenant. This is done interactively.
  3. Create the bulk enrollment token. This will generate a JSON file that has the details, but the New-AADIntBulkPRTToken cmdlet also returns the needed value. We specify an expiration date of 179 days in the future (the maximum is 180 days).
  4. Create an XML configuration file for the provisioning package using the BPRT value from the New-AADIntBulkPRTToken cmdlet.
  5. Find the ADK and the ICD.EXE file within it, then run an ICD.EXe command to generate the PPKG file from the XML configuration file.

The generated files (the XML configuration file and the PPKG that it generates) will use a default name of “BulkEnrollment-Expires-yyyy-MM-dd-hh-mm-ss” so you can easily keep track of when the file expires.

Here’s an example execution:

If we look in Azure AD, we can see the user object that it created:

You can find a copy of the script in the attached zip file.