PowerShell for the Windows Update for Business deployment service

Starting today, you can use PowerShell in tandem with Microsoft Graph APIs to utilize the Windows Update for Business deployment service. In case you aren't yet familiar with it, the Windows Update for Business deployment service provides cloud-based control over the approval, scheduling, and safeguarding of content delivered from Windows Update—enabling you to meet your organization's update and compliance goals no matter where your devices are on the planet.

In addition to Microsoft Graph APIs (currently in public preview), you can also use the Microsoft Graph PowerShell SDK to explore the latest functionality of the deployment service and quickly script and automate common update actions. It provides a simple way to get total control over how updates are deployed to your organization.

Now let's dive into a concrete example to demonstrate how you can leverage deployment service capabilities through PowerShell.

Walkthrough: How to deploy an expedited quality update

Let's say that Microsoft releases an update addressing a a high-priority security vulnerability or a quality fix for a critical line of business application that is crucial for your organization. In this case, you may want to deploy this update faster than your default update ring configuration. With PowerShell and the Windows Update for Business deployment service, you can deploy an expedited update, which overrides your default steady-state update settings and deploys the latest available updates so that your managed devices meet the minimum required Windows revision as quickly as possible.

Prerequisites

Before getting started, the following prerequisites must be met:

• Subscription service and device prerequisites for the Windows Update for Windows Update for Business deployment service
• Devices have installed the update described in KB4023057 - Update for Windows 10 Update Service components (or newer)

Assigning user roles for delegated permissions in PowerShell

Once you have confirmed that your tenant and devices meet the deployment service prerequisites, ensure your user account has one of the following permissions configured:

• Global Admin Role in Azure Active Directory
• Intune Admin Role in Azure Active Directory
• Policy and Profile Manager Role in Microsoft Intune
• Windows Update Deployment Administrator in Azure Active Directory

At least one of these roles is required for a user to be authorized to interact with the deployment service. To learn more, see Assign Azure AD roles to users and Assign a role to an Intune user.

Getting started with the Microsoft Graph PowerShell SDK

If you don’t already use PowerShell, your next step is to install a supported version of PowerShell. To learn how, see install PowerShell for your operating system.

Once you’ve installed PowerShell, ensure that you are running the latest version of the Microsoft Graph PowerShell SDK to be able to use the deployment service’s commands. You can install the SDK in PowerShell Core or Windows PowerShell using the following command:

 

 

 

Install-Module Microsoft.Graph

 

 

 

If you have already installed the Microsoft Graph PowerShell SDK, you can update the SDK and its dependencies using the following command. You must use version 1.6.0 or higher to use the deployment service:

 

 

 

Update-Module Microsoft.Graph

 

 

 

From this point on, every command will use the prefix Mg, which stands for Microsoft Graph. The deployment service is currently available through the beta endpoint of the Microsoft Graph, so you’ll need to set your user profile to the appropriate API contract.

 

 

 

Select-MgProfile -Name "beta"

 

 

 

Finally, use the Connect-MgGraph command to sign in. You'll need to sign in with an account assigned to one of the required roles to consent to the permissions specified under scopes in this command.

 

 

 

Connect-MgGraph -Scopes "WindowsUpdates.ReadWrite.All"

 

 

 

Once the Graph PowerShell SDK is installed and you are signed in, you’re ready to start scripting common actions in the deployment service.

If you’re using an automated script instead of the PowerShell console, you can use the PSCredential Class to automate usernames, passwords, and credentials. 

Step 1: Get a list of available updates

With expedited updates, you can speed the installation of quality updates like the most recent Update Tuesday release or an out-of-band security update for a zero-day flaw. An expedited deployment policy enables your devices below the minimum specified revision to override their default update posture and update as quickly as possible to the latest available update.

Let’s start by querying the deployment service catalog to get a list of security updates that can be specified as the minimum compliance bar for an expedited update. Below is an example of a query to the catalog that shows the quality updates available to expedite from most recent to last.  

 

 

 

Get-MgWindowsUpdatesCatalogEntry -Filter "microsoft.graph.windowsUpdates.qualityUpdateCatalogEntry/isExpeditable eq true"

 

 

 

The output of the query will look something like this:

Step 2: Create a deployment

Now we’ll create an expedited deployment. The content to deploy is specified using the releaseDate key (which specifies a compliance floor), and the device restart grace period is determined using the daysUntilForcedReboot property. Below is an example of creating a deployment for an expedited quality update.  

 

 

 

New-MgWindowsUpdatesDeployment -Content @{"@odata.type" = "microsoft.graph.windowsUpdates.expeditedQualityUpdatereference"; "releaseDate" = "2021-05-11"}

 

 

 

When the command successfully creates a deployment, it outputs something along the lines of the following:

Step 3: Assign devices to the deployment audience

Finally, let’s assign devices to the expedited deployment just created. Devices can be assigned directly or via an updatable asset group. Below is an example of adding an Azure AD device to a deployment using its ID. The DeploymentID comes from the response of the previous command.

 

 

 

Update-MgWindowsUpdatesDeploymentAudience -DeploymentID "a257062d-b716-43b9-99339-d13ea06eeeec" -AddMembers @(@{"id" = "dae37284-9dae-453a-aa61-dee371139090"; "@odata.type" = "Microsoft.graph.WindowsUpdates.azureADDevice"}) 

 

 

 

There’s no output from this command. Once you have assigned devices to the deployment audience, the deployment service will begin expediting updates as quickly as possible! You’ll be able to check the status of each device as your deployment progresses using Update Compliance.

Wrapping up

We hope that this example provides you with a practical tool for managing and responding to situations that require rapid deployment of quality updates while illustrating how you can use PowerShell to interact with the deployment service more generally. We encourage you to expedite an update within your organization and explore the broader set of capabilities available within the deployment service. Stay tuned for more examples!