Returning a managed device to service
Use a device management service to return managed devices to service quickly after use.
Overview
Organizations often have managed devices that multiple people use, such as shift workers who pick up, use, and return devices. When a person returns a device, the device management service needs to reset it to erase any data associated with that person, ensuring a clean device for the next person. The service sends an Erase Device command to reset the device, causing it to erase and return to the Setup Assistant screen for a new device. In some cases, the user or the device can directly trigger the return to service.
A device management service uses the Erase Device command in three ways:
- A simple erase
After the device management service erases the device, the device proceeds through the normal Setup Assistant flow. This option is available only for devices when their enrollment type is a device enrollment.
For devices using Automated Device Enrollment, the user needs to trigger the enroll operation during the Setup Assistant flow. The service sets Automated Device Enrollment SkipKeys to bypass other Setup Assistant screens, avoiding additional user interaction before the device completes setup.
For devices not using Automated Device Enrollment, the user needs to manually reenroll the device after proceeding through all the Setup Assistant screens.
- A standard return-to-service erase
When the device management service erases the device, the service provides additional data in the Erase Device command, allowing the device to proceed through Setup Assistant without any, or the minimum required, user interaction. This option is available only for devices when their enrollment type is a device enrollment.
- A return-to-service with app preservation erase
This option behaves like the previous flow, but it preserves managed apps during the erase, speeding up the return to service by avoiding downloading existing managed apps for the next user. In visionOS, users can trigger this flow themselves, and an admin can configure an idle device timeout to trigger the flow after a specified amount of time. This flow is available only for devices using Automated Device Enrollment.
The two return-to-service flows automate and speed up resetting and reenrolling devices. The app preservation flow is optimized for users needing managed apps. The standard return-to-service flow is available for iOS, iPad OS, tvOS, and visionOS devices. The return-to-service with app preservation flow is available for iOS, iPad OS, and visionOS devices.
Return a device to service
The device management service uses the Erase Device command to trigger the standard return-to-service flow for any device with a device enrollment. The service includes additional properties in the command to automatically reenroll the device after the erase operation completes, as the “Trigger return to service” section below discusses. After a device erases itself, the following sequence of operations occurs:
The device enters Setup Assistant.
The device automatically joins the Wi-Fi network specified by the device management service, if present.
The device automatically enrolls with the device management service specified by the device management service if present, or the service specified in its Automated Device Enrollment Profile.
The device proceeds through Setup Assistant (without requiring user interaction on iOS, and with a minimum required interaction on visionOS), entering and exiting the await configuration state that the device management service controls.
The device exits Setup Assistant and is ready to use.
If the device management service triggers the standard return-to-service flow again, the device erases itself and returns to step 1 in this sequence.
Trigger return to service
The device management service triggers each return-to-service flow by setting the ReturnToService key in the Erase Device command it sends. This key contains a dictionary with the following keys:
Key | Type | Content |
|---|---|---|
| Boolean | (Required) The key that, if |
| Data | (Optional) The enrollment profile the device installs after erasure when |
| Data | (Optional) The Wi-Fi profile the device installs after erasure when |
| Data | (Optional) The bootstrap token the device needs to erase itself when |
The device management service sets the Enabled key to true in the Erase Device command to ensure a return-to-service flow after the erase. The service deactivates any Activation Lock on the device before it sends the command. If the device has an Activation Lock, a user needs to be present during the Setup Assistant flow to activate it, which prevents a fully automatic return-to-service flow.
If the device only has a Wi-Fi connection, the device management service sets the /WiFiProfileData key in the Erase Device command to a value that’s a Base64-encoded profile with a WiFi payload. The device uses this key to join a Wi-Fi network and connect to the device management service to automatically enroll.
The device management service sets the MDMProfileData key in the Erase Device command for the following situations:
The device isn’t using Automated Device Enrollment. The device needs the enrollment profile to automatically reenroll.
The device is using Automated Device Enrollment and the Profile contains a
configuration-web-urlkey. The device needs the enrollment profile to automatically reenroll by bypassing the sign-in flow, which theconfiguration-web-urlkey normally triggers.The device is using Automated Device Enrollment and the Profile contains a
urlkey for an HTTP endpoint requiring HTTP authentication to fetch the enrollment profile. The device needs the enrollment profile to bypass this authentication flow and automatically reenroll.
The value of the MDMProfileData key needs to be a Base64-encoded profile with an MDM payload and any other necessary payloads.
The device management service only sets the BootstrapToken key in the Erase Device command when using the return-to-service with app preservation flow.
Return a device to service and preserve apps
The first time through the return-to-service with app preservation flow, the device downloads and installs managed apps that the device management service requires, and takes a snapshot of the system data volume. For subsequent times, after erasure, the device restores the last snapshot and doesn’t need to download the managed apps present in the snapshot, if the device management service reinstalls them. However, it does have to download other managed apps that the device management service adds.
The return-to-service with app preservation flow requires a device using Automated Device Enrollment. The device management service sets the is_return_to_service key to true in the Profile for the device to ensure app preservation. When that key is set, the device always assumes the value of the await_device_configured key in the Profile is true. This ensures the device enters the await configuration state, causing it to wait for the service to indicate when it can proceed. The service can then provision the device with an appropriate management state by sending commands before a user can access it. The service uses the await configuration state for app preservation as described below.
After the device first enrolls with the device management service, it sends its bootstrap token to the service using the Set Bootstrap Token check-in request. The service persists the bootstrap token and returns it when needed. The device can preserve apps only when it receives the bootstrap token from the service. Without the bootstrap token, the device performs a standard return-to-service flow without app preservation.
There are three ways to trigger the return-to-service with app preservation flow on the device:
Service triggered: The device management service sends a Erase Device command.
User triggered: The user triggers return to service on the device (visionOS only).
Device triggered: The device triggers return to service when it’s idle for a set amount of time (visionOS only).
Trigger a device from the device management service
The device management service uses the Erase Device command to trigger the device. The command has the same requirements as the standard return-to-service flow, described in the “Trigger return to service” section above, with the additional requirement that the BootstrapToken key is present and set to the bootstrap token value the device previously sent. When the device receives the command, it uses the bootstrap token to erase user data while preserving system data, including managed apps.
Handle the user trigger
On visionOS devices, a person can trigger the return-to-service with app preservation flow from the lock screen or control center. When they trigger the device, it sends a Return To Service check-in request to the device management service. The service includes a ReturnToService key in the ReturnToServiceResponse response, with that key matching the ReturnToService key in the Erase Device command. When the device processes the response, it uses the bootstrap token to erase user data while preserving system data, including managed apps.
Handle the device trigger
On visionOS devices, a device can trigger the return-to-service with app preservation flow when it’s idle for a set amount of time. To set a timeout, the device management service sends a Settings command with a SharedDeviceConfiguration object that contains the TemporarySessionTimeout key, and sets the value to the required timeout in seconds. The device doesn’t trigger an idle timeout if the value is zero or the setting isn’t present. When the device triggers the idle timeout, it uses the Return To Service check-in request to start the return-to-service flow, as the previous section describes.
Preserve apps
When the device uses the return-to-service with app preservation flow, after erasure, the following sequence of operations occurs:
The device enters Setup Assistant.
If it’s not the first time through the flow, the device restores the last snapshot it took. If a snapshot exists, it contains the device management service enrollment and any managed apps that were present when it took the snapshot.
The device saves a list of any managed apps that are present.
The device unenrolls from any device management service that is present, without removing managed apps.
The device joins the Wi-Fi network if the server set it prior to the erasure.
The device enrolls with the device management service using the enrollment profile the server set during erasure, or using the Automated Device Enrollment Profile to fetch an enrollment profile.
The device enters the await configuration state.
The device management service uses MDM commands or declarative management to provision the device, including any managed apps it wants preserved for the next time it triggers the flow. The device doesn’t have to download apps that it preserved in the previous snapshot.
The device management service sends the Device Configured command to exit the await configuration state.
The device immediately responds to the command, but doesn’t proceed through Setup Assistant.
The device pauses processing of device management commands, responding with
NotNowif it receives any further commands.The device waits for all provisioned, but not preserved, managed apps to download and install.
The device removes apps in the saved list that aren’t reinstalled.
The device takes a snapshot of the system data volume, including the new set of managed apps.
The device reenables processing of device management service commands. If it previously sent
NotNow, it sendsIdleto indicate readiness.The device automatically proceeds through Setup Assistant without requiring user interaction, except in visionOS, where the device requires the user to step through only the Setup Assistant screens that calibrate the headset.
The device exits Setup Assistant and is ready to use.
If an action triggers the flow again, the device erases itself and returns to step 1.
Handle software updates
The device disables software updates — both automatic and user-initiated — when the return-to-service with app preservation state is active because the device effectively reverts any OS update when restoring the snapshot taken in step 14 above.
The device management service can trigger a software update by returning the ErrorCodeSoftwareUpdateRequired HTTP 403 error code during enrollment in step 6 if using the service that its Profile specifies. In that case, the device does a software update, then reboots to restart the flow. Otherwise, a software update is possible only by turning off the return-to-service with app preservation flow.
Allow visionOS devices to join Wi-Fi on reboot
When a person finishes using an Apple Vision Pro device, they remove the headset and then often disconnect the device from its power source. When the next user picks up the device to use it, it does a “cold” boot when powered on and remains locked to the previous user. In order for the new user to trigger the return-to-service flow from the lock screen, the device needs to be on a Wi-Fi network so it can send requests to the device management service. However, after a cold boot, the device isn’t connected to Wi-Fi, preventing the new user from triggering the return-to-service flow.
To work around this situation, the device management service can install a WiFi payload on the device, and set the payload’s AllowJoinBeforeFirstUnlock key to true to allow the device to join that Wi-Fi network automatically after a cold boot. The following conditions apply when using the AllowJoinBeforeFirstUnlock key:
The device supports it only when in the return-to-service with app preservation mode.
The device allows it in only one Wi-Fi payload.
The Wi-Fi payload can’t include the
EAPClientConfigurationkey.The Wi-Fi payload’s
IsHotspotkey needs to be set tofalseor not be present.The Wi-Fi payload can’t include the
QoSMarkingPolicykey.The Wi-Fi payload’s
ProxyTypekey needs to be set toNoneor not be present.
When these conditions apply, the device places any Wi-Fi network credentials into Class D storage in its keychain, and it stores any other Wi-Fi network details in a file using Class D storage. The device makes items in Class D storage available after the cold boot, before first unlock. Thus the device uses those details to join the Wi-Fi network before first unlock.
To use this mechanism, the device management service needs to install this Wi-Fi profile in each cycle of return to service. The best time to install the profile is during the await configuration state, before the next user starts accessing the device.