Enforce latest OS when macOS, iOS, and iPadOS hosts automatically enroll

[nonpunctual]

Goal

User story
As an IT admin,
I want to require end-users to have a minimum OS version installed on the host before they enroll to MDM (with ADE)
so that I can make my new hosts compliant before they are enrolled into production.

Context

• Requestor(s): @nonpunctual
• Product designer: @marko-lisica

Research

During MDM enrollment, the device will respond with MachineInfo to the server when fetching the enrollment profile. The server needs to check if the device is on specified minimum OS version, if not server sends 403 error

More info here (Create a New Device Management Connection > step 3)

Changes

Product

• UI changes: Figma wireframes here.
• Other changes:
  • Enforce the latest macOS, iOS, or iPadOS during Setup assistant, if the host is below the minimum version set in Fleet. Let the end user through setup assistant w/o an upgrade if their host is above the minimum version set in Fleet.
  • Fleet will get the latest macOS from Apple here (Public AssetSets). If the request to Apple fails, Fleet will try again up to 3 times. If all attempts fail, Fleet will let the end user through Setup Assistant w/o an OS update.
  • This is supported only for hosts running macOS 14+ or iOS/iPadOS 17+ that automatically enroll (DEP). Apple only supports this feature in these scenarios.
• Outdated documentation changes: Add info to OS updates page: this applies only to ADE enrollment and hosts that run macOS 14 / iOS/iPadOS 17 and above. Add one sentence that describes this limitation and experience in the macOS section of the page.

Engineering

• Database schema migrations: TODO
• Load testing: TODO

ℹ️  Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

• Requires load testing: TODO
• Risk level: Low / High TODO
• Risk description: TODO

Manual testing steps

1. Step 1
2. Step 2
3. Step 3

Testing notes

Confirmation

1. Engineer (@____): Added comment to user story confirming successful completion of QA.
2. QA (@____): Added comment to user story confirming successful completion of QA.

[noahtalerman]

Thanks @nonpunctual. Really helpful link to Filewave docs.

We'll weight this at the next feature fest on 2024-06-20.

[nonpunctual]

Apple guide for "Managing software updates for IT" updated June 2024 per WWDC
managing-software-updates-v1-0.pdf

[lashomb]

This would be really nice to replace some problematic lagacy policies we have to do this now.

[nonpunctual]

@lashomb added customer label to this issue. Thanks!

[marko-lisica]

@nonpunctual I converted the original issue description to user story format. Moving original here.

Apple has added a feature for denying enrollment if a device is not on a specified, minimum OS version.

Property from the schema documented at https://developer.apple.com/documentation/devicemanagement/machineinfo -

Property: MDM_CAN_REQUEST_SOFTWARE_UPDATE
Type: boolean
Value: If TRUE indicates that the (MDM) server can trigger the (enrolling) device to do a required software update. Available on iOS 17 and later, and macOS 14 and later.
Default value: false

From https://github.com/apple/device-management/blob/release/mdm/errors/softwareupdate.required.yaml -

The schema for a JSON or property list XML document returned in an MDM server's 403 response body. The response headers must include a "Content-Type" header indicating whether JSON or XML is being returned.

This response is returned when a device is enrolling with an MDM server during Setup Assistant, and the MDM server
requires the device to perform a software update before enrollment is allowed and setup can proceed.

In order for users to take advantage of this feature Fleet must be enabled to:

• recognize devices in the state of NOT matching the minimum specified OS version at MDM enrollment in the MachineInfo config
• send the correctly formatted error response to the enrolling device

Problem

Fleet is not currently enabled to deny MDM enrollment based on a specified minimum OS version.

Potential solutions

1. Add the ability to recognize the MachineInfo properties to Fleet MDM
2. Enable the response for devices that do not match a specified minimum OS version

Documentation for this feature in Filewave https://kb.filewave.com/books/apple-school-business-manager/page/minimum-os-version-for-enrolling-apple-devices-via-ade

[noahtalerman]

Hey @nonpunctual I pulled the ~feature fest off because this story is in the current design sprint :) You can tell if it has :product

Please check before adding requests to feature fest. Thanks!

[georgekarrv]

@roperzh when you get some time can you review this and make sure we have a good understanding of all of the steps needed to both identify and deliver this specific case? When that's done go ahead and pull this over to specified.

[roperzh]

This should apply only on hosts running macOS 14 and above or iOS/iPadOS 17 and above that are enrolling through ADE

as I understand this flow is available for manual enrollments too, any reason to limit it to ADE?

edit: I was wrong, seems like it's ADE only, sorry!

@marko-lisica or @nonpunctual (not sure who added this section)

[georgekarrv]

Hey team! Please add your planning poker estimate with Zenhub @dantecatalfamo @ghernandez345 @gillespi314 @jahzielv @mna @roperzh

[nonpunctual]

[noahtalerman]

Hey @gillespi314, when you get the chance, does the OS update happen before Fleet sends any MDM commands? (InstallApplication, InstallProfile, etc.)

customer-eponym is wondering...

[gillespi314]

Hey @gillespi314, when you get the chance, does the OS update happen before Fleet sends any MDM commands? (InstallApplication, InstallProfile, etc.)

customer-eponym is wondering...

Yes, it is enforced by Apple before the device is allowed to download the enrollment profile.

[noahtalerman]

Hey @gillespi314 we just learned this from customer-rosner:

• having newly onboarded folks getting updated to a version of macOS that isn't compatible with the latest CrowdStrike sensor, etc would be badddd....

This means that our current approach (always updating to latest no matter what) would make folks nervous (at the least) or create a poor onboarding experience (at the worst).

I met with @georgekarrv and we think it makes sense to make the following change this sprint:

Enforce the latest macOS, iOS, or iPadOS during Setup assistant, if the host is below the minimum version set in Fleet. Let the end user through setup assistant w/o an upgrade if their host is above the minimum version set in Fleet.

I updated the issue description (specs) to reflect that^

If you have questions or concerns please feel free to schedule some time w/ me! Thanks :)

[lashomb]

Enforce the latest macOS, iOS, or iPadOS during Setup assistant, if the host is below the minimum version set in Fleet. Let the end user through setup assistant w/o an upgrade if their host is above the minimum version set in Fleet.

This would probably be the safest, I like that approach as well.

[PezHub]

QA Notes:

• Ensured that macOS hosts can enroll without a forced update if it’s above the minimum required OS set in Fleet
• Ensured macOS hosts get forced to update if below the minimum required OS set in Fleet
• @georgekarrv was able to test iOS and iPadOS workflows

Tests:

• Set minimum ver to 14.6.1 (latest) and DEP enrolled my mbair running 14.4.1 successfully after the forced upgrade.
• Set the minimum to 14.5 and got the prompt to force an update to 14.6.1 (latest) and successfully installed
• Set the minimum ver to 14.0 and successfully DEP enrolled my mbair running 14.4.1 without any prompts to upgrade
• Edge case:
  - set the ver to 14.9.0 (non-existant/not released) and DEP enrolled my host running 14.6 without any prompts
  - set the ver to 14.9.0 and enrolled my host running 14.4.1 and was forced to upgrade to 14.6

This is the screen the user is presented with prior to enrollment

Additional note:
@noahtalerman after re-installing 14.4.1 on my device, I moved it to another team that had a minimum OS set to 14.5 and ensured DDM worked as expected. I received the prompt that a scheduled update was set for 14.5 (not 14.6 latest)

[noahtalerman]

Thanks @PezHub!

@noahtalerman after re-installing 14.4.1 on my device, I moved it to another team that had a minimum OS set to 14.5 and ensured DDM worked as expected. I received the prompt that a scheduled update was set for 14.5 (not 14.6 latest)

Is this the same for iOS and iPadOS?

Assuming yes, @georgekarrv I think we want to call out this difference in behavior in the UI so that the IT admin knows.

I think this can be a quick tooltip update as designed in Figma here: https://www.figma.com/design/8anmUdAjxircEGfraBTiBu/%2319674-Enforce-latest-OS-when-macOS%2C-iOS%2C-and-iPadOS-hosts-automatically-enroll?node-id=0-1&t=9iYPY3Ej8krZCVGP-1

Do you think we can squeeze that copy update in before we ship the release?

I added the above Figma wireframes to the Product section in the GitHub issue.

[georgekarrv]

From what I have seen my ios devices could only update to the latest. I may have missed this case specifically though

[noahtalerman]

@georgekarrv I think we want to call out this difference in behavior in the UI so that the IT admin knows.

I think this can be a quick tooltip update as designed in Figma here: https://www.figma.com/design/8anmUdAjxircEGfraBTiBu/%2319674-Enforce-latest-OS-when-macOS%2C-iOS%2C-and-iPadOS-hosts-automatically-enroll?node-id=0-1&t=9iYPY3Ej8krZCVGP-1

Do you think we can squeeze that copy update in before we ship the release?

Hey @georgekarrv, I forgot to follow up on this so we didn't get the testing/tooltip copy in before shipping this story.

I filed a bug here for testing and tooltip copy update: #21976

I think let's address that bug as soon as we can (top priority below priority tickets) so we can close this story out.

cc @gillespi314 @lukeheath

[noahtalerman]

Hey @georgekarrv just giving you an extra ping! re this comment.

[noahtalerman]

Hey @zayhanlon and @dherder heads up that this customer/prospect request was shipped!

We're leaving it open until we ship a copy change (bug) but the core functionality is ready to use.

[noahtalerman]

Pulling this out of Slack:

Sarah: For OS updates post-enrollment, we’re trying to understand how to describe how DDM OS updates work. Can we accurately say that “If an already enrolled host is below the minimum version [specified in Fleet], the host is updated to exactly the minimum version [specified in Fleet].”
My understanding is that we can’t guarantee that it will be exactly the version specified in Fleet because there are some not very well documented limitations based on what is available in AssetSets from gdmf .

Roberto: this document (shared a couple of times in this channel) is great. I think it answers all our questions
my reading is that as Sarah suspected, and Gabe confirmed, you can only pick versions from AssetSets in gdmf
also looks like they expect MDM vendors to query this (see under "Using the Apple Software Lookup Service")

managing-software-updates-v1-0 (2).pdf

Sarah: Yep, I referenced this too. I think our current task is to confirm this documentation can be trusted and sus out edge cases as best we can. Then try to describe it all to our end users in a way that makes sense with our current UX where we offer users a free text field (where we assumed that old versions aren’t being removed) while Apple has designed this with ever-changing additions and deletions. For MDM providers like us, we need to provide UX for two paths:
When an IT admin wants to set the minimum version, we need to offer them a list that matches the current AssetSets and limit their choices to that list
When Apple changes the AssetSets to remove a version that was previously set in Fleet, we need some kind of UX to surface that issue to the IT admin and let them take action (or at least explicitly define whatever action Fleet will take by default in that scenario).

George: I think instead of the perfect UX or the perfect tooltip we need to just figure out how to explain this behavior for this ticket and open a feature request to improve it to get this closed in this release.
If an already enrolled host is below the minimum version, the host will try to be updated to exactly the minimum version if available from Apples hosted versions.

If the minimum version is no longer available from Apple the update will not be scheduled.

If a new or wiped host is below the minimum version and automatically enrolls (ADE), the host is updated to Apple's lastest version during Setup Assistant.

George: The problem is it is wrong because we cannot got to exactly the minimum version when it's not on gdmf anymore

Noah: Got it! Then, I think let’s go w/ a simpler version of George’s copy. This link doesn’t tell me the versions available.

If an already enrolled host is below the minimum version, the host is updated to exactly the minimum version if it’s available from Apple.

If a new or wiped host is below the minimum version and automatically enrolls (ADE), the host is updated to Apple’s lastest version during Setup Assistant.

[noahtalerman]

Waiting on this bug fix before we close this story: #21976 (comment)

cc @ghernandez345

[ghernandez345]

@noahtalerman this is now done and was merged in with this PR #22337

[noahtalerman]

@ghernandez345 thanks!

Do you think we should re-open the bug and bring it back onto the release board? So it gets QA'd.

cc @georgekarrv

[noahtalerman]

UPDATE: Closing this user story. I checked to make sure that the redirect in the UI works: https://fleetdm.com/learn-more-about/available-os-update-versions

[fleet-release]

In cloud city's glow,
Fleet ensures OS up-to-date,
Smooth enrollment bestows.