Use MDM to deploy software updates to Apple devices

The importance of leveraging software update declarations

MDM solutions should leverage software update declarations whenever possible. However, the legacy software update commands and profiles are still available and supported. They can work alongside software update declarations with the following changes:

• Deferrals defined by a declaration take precedence over deferrals configured by a restriction.

• Automatic software update settings on macOS applied by a declaration take precedence over automatic update settings provided in a configuration profile.

• When there’s a pending software update configured using declarative device management, some MDM commands are no longer processed by the client, returning errors communicating that there’s an active declaration on the device, as shown in the following table:

Using the Apple Software Lookup Service

The Apple Software Lookup Service (available at https://gdmf.apple.com/v2/pmv) is the official resource to obtain a list of publicly available updates, upgrades, and Rapid Security Responses. It allows an MDM solution to query releases as soon as they are published and calculate applicability for each hardware model in a timely and accurate manner.

The JSON response contains three lists of available software releases:

• PublicAssetSets: This list contains the latest releases available to the general public if they try to update or upgrade.

• AssetSets: This list is a subset of PublicAssetSets and contains all the releases available for MDM solutions to push to supervised devices.

• PublicRapidSecurityResponses: This list contains Rapid Security Response releases currently available for Apple devices.

Each element in the list contains the ProductVersion number and Build of the operating system, the PostingDate when the release was published, the ExpirationDate, and a list of SupportedDevices for that release. The device list matches the ProductName value from the device, which is returned in a DeviceInformation response, the initial Authenticate request, or in the MachineInfo when the device tries to enroll.

The expiration date, typically set to 180 days after the posting date, defines the date the signing of the update expires. An expired update can’t be installed on devices anymore. When subsequent updates are made available, previous updates might have their expiration dates updated. If an expiration date isn’t provided, the update has yet to expire. An update has expired only when it has an expiration date in the past.

The assets are grouped by operating system platform using the following keys:

• iOS (which includes iPadOS, tvOS, and watchOS)

• macOS

• xrOS (which is visionOS)

Use the product version list to determine which versions are greater than the deviceʼs current operating system version and are applicable to a specific device. Provide that list of versions to the MDM administrator as potential operating system update candidates.

Sending a status report to the MDM solution

To receive updates for status items as they change, the server must subscribe to each status report by sending a ManagementStatusSubscriptions declaration to the device. The device then sends a StatusReport to the MDM solution when a ManagementStatusSubscriptions declaration becomes active, if the status of a subscribed item changes, and every 24 hours.

For the purposes of monitoring operating system versions and software update status, the MDM solution may want to subscribe to the following status reports:

In addition to the other reports, MDM solutions may also want to make softwareupdate.install-reason available to administrators for support purposes and to provide additional insight into how an update got triggered. This dictionary can be used to determine whether a user has initiated the update themselves, the update happened automatically, or it got enforced by a software update enforcement declaration.

Requesting a specific minimum software version during MDM enrollment

If a device supports this capability, it returns an MDM_CAN_REQUEST_SOFTWARE_UPDATE key, set to True, in the MachineInfo data that it sends in the initial HTTP POST request to the MDM solution when the device detects a management configuration in Setup Assistant. For more information, see the MachineInfo yaml file in the Apple device management GitHub repository.

In addition, devices provide the following fields in the MachineInfo data (all strings) :

Based on the information provided, the MDM solution can decide whether to enforce the device to update.

• If an MDM solution chooses not to enforce a software update, it simply returns the MDM enrollment profile in response to the HTTP POST request, as it would normally do to allow an MDM enrollment to proceed.

• If the MDM solution chooses to enforce a software update then it must return an HTTP response with the 403 status code, and include a JSON or XML object in the response body (the HTTP Content-Type response header must be set to application/json or application/xml respectively).

After receiving this error response, the device attempts to update to the specified version. If the update succeeds, the device restarts and the user must go through Setup Assistant again. The next MachineInfo POST request from the device to the MDM solution shows the updated operating system version, and the MDM solution can then proceed with MDM enrollment. If the update fails, an error is shown to the user and the Remote Management pane appears in Setup Assistant again.

The response schema is defined in the table below.

The details dictionary schema is defined here.

If only the OSVersion is specified, a device automatically downloads and installs any Rapid Security Responses available for this version. In case a specific build or supplemental version is needed, an MDM solution can also optionally specify the BuildVersion. For example, to require a device to run iOS 16.5.1(a) before enrolling—although iOS 16.5.1(c) is already available—an MDM solution must set OSVersion to iOS 16.5.1 and BuildVersion to 20F770750b.

MDM settings for software updates

The com.apple.configuration.softwareupdate.settings declaration (available in iOS 18, iPadOS 18, and macOS 15) consists of dictionaries that can be used to configure various aspects of the software update behavior.

After an MDM solution distributes different keys across multiple declarations, a device merges the settings of all active software update settings declarations. In case the same key is configured by multiple declarations, the merge behavior depends on the individual key and is outlined in the tables below.

Configuring automatic software updates with MDM

The com.apple.configuration.softwareupdate.settings declaration offers a dictionary to define the automatic software update behavior on supervised iPhone, iPad, and Mac devices. For more information, see AutomaticActions dictionary keys.

How MDM handles Rapid Security Responses

Rapid Security Responses always apply to the latest update of an operating system, which becomes the base version of the Rapid Security Response. For example, if an iPhone has operating system version iOS 17.2 installed, then it applies the 17.2 (a) supplemental update, if one is available. In iOS 18, iPadOS 18, and macOS 15, combined updates have been made available, which allow a software update to include any available Rapid Security Responses.

Prior to iOS 18, iPadOS 18, and macOS 15, an MDM solution may have to trigger two software updates to ensure that a specific supplemental version is present: first, it must update the device to the base version of the supplemental update, if the device isn’t already on that base version (for example, iOS 17.1 to iOS 17.2); then it must update the base version to the supplemental version (for example, iOS 17.2 to iOS 17.2 (a)).

In iOS 18, iPadOS 18, and macOS 15, an MDM solution can specify either:

• The operating system version (which automatically installs available Rapid Security Responses)

• The supplemental build version (which causes the device to perform a necessary update to the base version automatically as part of the process)

These two approaches apply to the software update enforcement configuration, and to the enforced minimum version during Automated Device Enrollment.

The com.apple.configuration.softwareupdate.settings declaration can also be used to configure the Rapid Security Response behavior on supervised iPhone, iPad, and Mac devices. For more information, see RapidSecurityResponse dictionary keys for iOS, iPadOS, and macOS.

Deferring a software update with MDM

Deferring a software update or upgrade from 1 to 90 days is done using the com.apple.configuration.softwareupdate.settings declaration on supervised iPhone, iPad, and Mac devices.

A configured deferral defines how many days a release isn’t offered to users after it became publicly available. Independent of a configured deferral, an MDM solution can still enforce a specific software update, upgrade, or Rapid Security Response on managed devices. For more information, see Deferrals dictionary keys for iOS and iPadOS and Deferrals dictionary keys for macOS.

Enforcing software updates with MDM

To enforce a software update by a certain time on devices enrolled using Device Enrollment or Automated Device Enrollment, MDM solutions can apply the com.apple.configuration.softwareupdate.enforcement.specific declaration.

If a configuration specifies an operating system or build version that’s the same as, or older than the current device version, then the configuration is ignored.

If multiple configurations are present with a newer operating system or build version than the current device version, the configuration with the earliest target date and time is processed first, and any others remain in the queue. When the device updates to a new version, the set of configurations are reprocessed to determine which becomes the next one to be processed.

Any available Rapid Security Responses are automatically installed if an MDM solution defines only the TargetOSVersion. To target a specific release or Rapid Security Response, an MDM solution can use the TargetBuildVersion key in addition to specifying the build, including the supplemental version identifier.

For more information, see Enforce software updates dictionary keys.

Notifications

The Notifications key changes the default notification behavior to show only a notification 1 hour before the enforcement time and the restart countdown. For more information, see Notifications key.

Using the bootstrap token for Mac computers with Apple silicon

To authorize an enforced software update on a supervised Mac computer with Apple silicon, an MDM solution can request and escrow a bootstrap token. This allows for a completely seamless software update experience and avoids the need for user interaction as part of the process. When needed, the device uses a GetBootstrapTokenRequest to retrieve the bootstrap token from the MDM solution.

In the first step, the MDM solution determines whether the device supports a bootstrap token using the SecurityInfo command. If the response includes a BootstrapTokenRequiredForSoftwareUpdate that’s set to true, the device can use a bootstrap token to authorize a software update.

To get a bootstrap token created, the MDM solution must add com.apple.mdm.bootstraptoken to the ServerCapabilities array in the MDM profile. For more information, see the MDM payload on the Apple Developer website.

After the device receives the bootstrap token, it creates a bootstrap token the next time a Secure Token-enabled user logs in. It then reaches out to the check-in endpoint of the MDM solution and escrows the token using a SetBootstrapTokenRequest. For more information, see Set Bootstrap Token on the Apple Developer website.

For the most current schema specification, see the Apple device management GitHub repository.