Improve end user MDM migration workflow on macOS

[marko-lisica]

Goal

User story
As an end-user,
I want to know that I might see a system notification and I only want to see Fleet dialog if my Mac is not in ABM
so that I have an easy time migrating to the new MDM solution.

Context

• Product designer: @marko-lisica

macOS 14 (Sonoma) introduced a new experience for macOS hosts in Apple Business Manager. Instead of a notification that appears in notification center, new dialog pops up over whole screen. In "Forced" migration mode, Fleet shows a window every 15 minutes to end user, telling them to start migration process.This Fleet window conflicts with new macOS Sonoma experience.

Changes

Product

• UI changes: Figma link
• Outdated documentation changes: Cleanup and update this page. Remove default migration workflow and leave only end user workflow.
• Fleet's agent (fleetd) changes: Create a local file to track if migration workflow is enabled and if the host has MDM turned off. This way, fleetd knows when to show the new "Please connect to the internet" window if the host is offline.
  • For this story we're using the local file solution instead of building persistent storage. Why?
  • We want to prioritize moving quickly now. We can push off handling backwards compatibility later.
  • Regarding backwards compatibility, let's say in the future we decide to add persistent storage to fleetd. At this point we'll maintain the local file solution for migration until there are no Fleet customers migrating. At that point, we'll remove the local file solution in favor of persistent storage.

Engineering

• Guides: Update/test the following guide using the latest migration workflow built in this story: https://fleetdm.com/guides/mdm-migration
  • PR is here: feat: update MDM migration guide with new UX #22128
• Database schema migrations: TODO
• Load testing: TODO
• REST API changes: 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. Make sure that nothing breaks if Fleet run the command to open Apple's Remote Management pane when the Remote Management pane is already there.
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.

[marko-lisica]

Hey @georgekarrv, this one is ready to be specified.

[noahtalerman]

Hey @marko-lisica, @roperzh, and @georgekarrv, I added the decision we landed on ("local file solution" for handling hosts that disconnect from Wi-Fi) to the "fleetd changes" section in the issue description.

I included the rationale for going with this approach.

Please feel free to tweak it if I'm missing anything.

Also, George, heads up that it will be helpful for planning if we carve out a subtask for handling hosts that disconnect from Wi-Fi. This way, if it ends up being somewhat large (5-8), we can cut this.

Let me know how Marko or I can be helpful w/ spec'ing so we can get this one to tomorrow's estimation. Thanks!

[lukeheath]

@zayhanlon @dherder FYI this story is pushed to 4.56.0. We're confident it will ship in 4.56.0.

[jahzielv]

Note: we decided to remove the on-demand showing of the macOS Remote Management modal, because:

1. To do so, we'd need a form of IPC between Fleet Desktop and Orbit, and implementing it would take too long.
2. The user is already being prompted with the Remote Management modal every minute after unenrollment.

cc @noahtalerman

[noahtalerman]

Pulled the below from MDM daily standup (internal):

MDM migration: we won’t be able to cover the case where a host is manually enrolled but added in ABM after all. This is due to a limitation of the profiles show command on macOS; it is client-side rate limited after 10 calls (it returns a locally cached response after the 10th call). This is possibly something we could figure out in a future iteration, but recommend that we just move forward with this limitation for now since there are other big stories we need to get done as well.

Hey @jahzielv just following up to make sure if I’m understanding correctly.

We will now run the sudo profiles --type show command and show the Apple Remote Management screen (Figma here) if the host was manually enrolled.

But, if we hit the rate limit w/ the sudo profiles command for some reason then we’ll show Fleet's My device page (Figma here) instead.

Sound right?

[jahzielv]

Hey @noahtalerman sorry, I think I might not have explained it well!

I was referring to the case where a host might be manually enrolled in a 3rd party MDM, but assigned to Fleet via ABM. We said that we'd want that host to go through the ADE migration flow. To detect this case, we were going to use profiles show -type enrollment in Fleet Desktop. This command would tell us if the host was assigned to Fleet in ABM. There are 2 issues with this approach though:

1. Apple does a client-side rate limit on the profiles show -type enrollment command. It can be called a max of 10 times per 23 hour period. After that, the command returns a locally cached response.
2. A bigger issue: it turns out that that command also needs to be run as root with sudo, which is not possible in Fleet Desktop. We can't really make Orbit run it for Fleet Desktop due to a lack of inter-process communication.

[noahtalerman]

case where a host might be manually enrolled in a 3rd party MDM, but assigned to Fleet via ABM. We said that we'd want that host to go through the ADE migration flow.

@jahzielv that's right!

To detect this case, we were going to use profiles show -type enrollment in Fleet Desktop.

Why do we have to run the command? Don't we already know it's in ABM tho? Because we hit ABM API to get all hosts.

[noahtalerman]

Unrelated to the above comment:

@marko-lisica, @PezHub, and @georgekarrv I was looking at the copy for macOS < 14 and I think we might be missing a step (I could be wrong).

I think the end user has to click on the macOS notification to get the profile to show up in System Settings. Is that right?

If Marko can't remember, George and Gabe can we please check this during QA?

Thanks!

[marko-lisica]

@noahtalerman Thanks for catching this. I'm not sure if a user needs to click on the notification, so would be great to test that.

[jahzielv]

I was looking at the copy for macOS < 14 and I think we might be missing a step (I could be wrong).

@marko-lisica and I confirmed this earlier today on a call. He'll have a copy update for me to implement in the AM.

[jahzielv]

Why do we have to run the command? Don't we already know it's in ABM tho? Because we hit ABM API to get all hosts.

We need that command on the host to know which migration flow to send the user down. Fleet can only tell fleetd that some migration is needed, not which one specifically.

[noahtalerman]

Fleet can only tell fleetd that some migration is needed, not which one specifically.

@jahzielv doesn't fleetd know whether it's in ABM or not? And if it is, go through the automatic enrollment migration (Remote Management screen)

[jahzielv]

@noahtalerman

doesn't fleetd know whether it's in ABM or not? And if it is, go through the automatic enrollment migration (Remote Management screen)

Fleet does know, but it only sends a single type of notification to fleetd to indicate whether a migration is needed, not which type. As currently implemented, the type is determined purely on fleetd. We'd need to change the notifications flow to make Fleet tell fleetd which type of migration to do in this case.

As currently implemented, I believe that the Remote Management modal will be launched, but the swift dialog modal will have the images and copy for the manual case.

Perhaps this is a bug we could come back for in a quick improvement (only suggesting that because it's a very edge case)?

[noahtalerman]

Thanks @jahzielv!

As currently implemented, I believe that the Remote Management modal will be launched, but the swift dialog modal will have the images and copy for the manual case.

Perhaps this is a bug we could come back for in a quick improvement (only suggesting that because it's a very edge case)?

Up to @marko-lisica.

[marko-lisica]

Perhaps this is a bug we could come back for in a quick improvement (only suggesting that because it's a very edge case)

@jahzielv I agree, this is an edge case and I think we shouldn't change anything right now, in order to move quickly. We can always improve this later if we learn this is a real problem.

cc @noahtalerman

[PezHub]

QA Notes:

I was able to test the following -

• Forced Mode
• Voluntary Mode
• ADE migration workflow (both OS versions)
• Manual workflow for macOS 14 (not supported in ver 13)
• Confirmed choosing the 'later' button allows users to manually kick-off migration thru fleetd menu drop down
• Confirmed all links resolves to Contact IT URLs
• Confirmed offline and something's gone wrong error modal
• Confirmed Copy Changes for all scenarios
• Confirmed webhook functionality works as expected for removing old enrollment profiles

test notes and screenshots -

macOS 13 Ventura

macOS 14


Error modals -

[noahtalerman]

Guides: Update/test the following guide using the latest migration workflow built in this story: https://fleetdm.com/guides/mdm-migration

Hey @gillespi314 and @jahzielv, heads up I added the above the "Engineering" section in the issue. Can you please update the guide as part of this story? This is for to the following OKR:

A tutorial (article) exists that IT admins can follow to migrate to Fleet in the minimal number of steps.

[noahtalerman]

cc @georgekarrv ^^

[noahtalerman]

Hey @jahzielv, just following up on my comment here. Did we update this guide?

[jahzielv]

hey @noahtalerman , thanks for the ping! Looks like it fell between the cracks 😓

I'll own getting that guide updated ASAP!

I created a bug here: #22097 so it won't get lost in the sauce this time.

[noahtalerman]

Thanks @jahzielv!