Pre-fill and lock local account creation screen during out-of-the-box macOS setup

[roperzh]

Goal

User story
As an IT admin,
I want to pre-fill and lock the full name and account name w/ values from my IdP during out-of-the-box macOS setup
so that my end user's login to their Mac w/ their IdP username.

Context

• Product designer: @marko-lisica

Changes

Product

• UI changes: Figma link
• CLI changes: Figma link
• REST API changes: API design: Pre-fill and lock local account creation screen during out-of-the-box macOS setup #17118
• Permissions changes:
  • Admins, maintainers (team and global) and GitOps users can upload automatic enrollment profile
  • Admins, maintainers (team and global) and GitOps users can enable the advanced option to release the device manually from await_device_configured
• Other changes:
  • Set await_device_configured to true in the DEP profile for existing users (migration)
  • Update the order of commands that Fleet sends during enrollment:
    1. Command to install fleetd
    2. Command to install bootstrap package
    3. Command to install profiles
    4. Command to set up account (it's AccountConfiguration)
    5. Command to release host from Await Configured (DeviceConfigured)
  • If enable_release_device_manually set to true, Fleet won't send DeviceConfigured command. (user must send it manually)
• Redirection URL: PR link
• Outdated documentation changes: Cleanup and reduce of macOS setup page and document default behaviour when end-user authentication enabled.
• Changes to paid features or tiers: Fleet Premium only

Engineering

• Database schema migrations: TODO
• Load testing: TODO

Context

This is possible today however Fleet requires that the IT admin does the following:

• Configure end user authentication
• Set await_device_configured to true in their automatic enrollment (DEP) profile
• Build an automation to release the device from Await Configuration. We want Fleet to do this for the IT admin, by default.

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]

Hey @roperzh heads up, I moved the original issue description here:

Problem

DEP enrollment can be configured with await_device_configured, from the docs:

await_device_configured If true, the device will not continue in Setup Assistant until the MDM server sends a command that states the device is configured (see Release Device from Await Configuration).

Some IT admins use this to configure the device (install profiles, apps, etc) before it can continue with the setup during unboxing.

Potential Solutions

TBD: We need to design a flow for this use case

[noahtalerman]

Hey @marko-lisica I recorded a Loom video w/ my feedback here (internal).

Also, I left some feedback as TODOs in the design review doc (internal): https://docs.google.com/document/d/1AduqZ9yuMQ8uvC5Z6GJFJtE0pbdqdX9zHIau_VCOqGI/edit

[mna]

@noahtalerman @marko-lisica We tested the feature (with @ghernandez345 and help from Roberto on how to reset the device between DEP-enrollment tests), in general it should release the device relatively quickly (in about a minute) as it waits for all profiles to be deployed, and in the worse case it "gives up" waiting for all profiles/commands to be done after about 15 minutes, but the manual release (fleetctl mdm run-command with a DeviceConfigured payload) can always be sent to release it faster.

[noahtalerman]

@mna thanks for the update!

Testing DEP is a pain in the butt.

in the worse case it "gives up" waiting for all profiles/commands to be done after about 15 minutes

This is the case when the host goes offline while it's waiting for all profiles/commands?

Or does this happen in other scenarios? (poor connection/slow internet)

Asking because, if it's the offline case, I think sending the DeviceConfigured won't work (host won't receive the command).

[mna]

@noahtalerman

This is the case when the host goes offline while it's waiting for all profiles/commands?

Yes, or any other reason why it didn't yet process all DEP enrollment commands and initial custom profiles, e.g. if battery is low and the device sends a "NotNow" response to commands, or network issues/slowness as you mention, etc.

if it's the offline case, I think sending the DeviceConfigured won't work

You're correct, but it doesn't really "send" the DeviceConfigured command, it enqueues it to be sent, so that whenever the device starts processing commands again, it will receive it.

[noahtalerman]

it enqueues it to be sent, so that whenever the device starts processing commands again, it will receive it.

@mna ah, I see. So if the device sends a bunch of "NotNow" responses and the user is stuck for awhile, the IT admin can queue up the DeviceConfigured command.

This command will run sooner than retries for the commands that responded "NotNow" so the user will get unstuck.

Is that right?

Sounds like we can optimize this later by adding some sort of countdown (let's say 5 minutes) before Fleet just sends the DeviceConfigured command.

If so, I think the current way it works is acceptable.

[mna]

This command will run sooner than retries for the commands that responded "NotNow" so the user will get unstuck.

@noahtalerman That's my understanding, yes. "NotNow" commands are skipped during "NotNow" responses.

[noahtalerman]

API changes are merged.

TODO @noahtalerman remove duplicate example automatic enrollment (DEP) profile: https://github.com/fleetdm/fleet/blob/main/tools/mdm/apple/dep_sample_profile.json

Let's point users to the one we dogfood: https://github.com/fleetdm/fleet/blob/main/it-and-security/lib/automatic-enrollment.dep.json

[noahtalerman]

UPDATE: PR is merged

PR to remove the duplicate DEP profile is here: #18114

[noahtalerman]

Outdated documentation changes: Cleanup and reduce of macOS setup page and document default behaviour when end-user authentication enabled.

PR is here: #18127

[noahtalerman]

Hey @Patagonia121 heads up, this customer request was shipped! 🎉

Docs are in progress. PR is here: #18127

[noahtalerman]

Docs PR is merged! #18127

[fleet-release]

Mac setup streamlined,
Like a cloud city's rhythm,
Admins find peace of mind.

[noahtalerman]

Re-opening this story because we're missing some API docs. More info here: #16728 (comment)

@rachaelshaw when you get the chance, can you please update the docs. Thanks!

[noahtalerman]

UPDATE: Doc PR is here: #19225

TODO:

• Update API docs per Martin's comment here: Recategorize & reorganize /mdm/ REST API endpoints #16728 (comment)
• Update permissions docs to consolidate all of Setup experience into one or two rows

@noahtalerman

[rachaelshaw]

Docs are merged ✅

[fleet-release]

Mac set-up now eased,
like dandelions in breeze,
Fleet fills in with ease.