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 usage changes: Figma link
• [ ] REST API changes: #17118
• [ ] Permissions changes:
  • Admins and maintainers (team and global) can upload automatic enrollment profile
  • Admins and maintainers (team and global) 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)
• [x] 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

[noahtalerman]

In your IdP, make sure the end user's full name is set to one of the following attributes (depends on IdP): name, displayname, cn, urn:oid:2.5.4.3, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. Fleet will populate the Full Name with any of these.

In your IdP configuration set Name ID to the end user's email. Fleet will trim this email and use it to populate the Account Name. For example, a "[email protected]" email turn into a "johndoe" Account Name.

Hey @roperzh, at some point we discussed the above IdP-side config requirements for Fleet to set the Full Name and Account Name. (for users releasing the host manually)

Is the plan to require the same IdP-side config for this feature? (users rely on Fleet to release the host)

[roperzh]

@noahtalerman I think so! we can always make tweaks or ask the IT admin to set different attributes in their idP config for a better UX though.

[noahtalerman]

@roperzh got it! Agreed we can improve it but I think this is good for the first iteration.

In your IdP, make sure the end user's full name is set to one of the following attributes (depends on IdP): name, displayname, cn, urn:oid:2.5.4.3, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. Fleet will populate the Full Name with any of these.

In your IdP configuration set Name ID to the end user's email. Fleet will trim this email and use it to populate the Account Name. For example, a "[email protected]" email turn into a "johndoe" Account Name.

@weswhet what do you think?

[mna]

@noahtalerman @marko-lisica Regarding the permissions:

Admins and maintainers (team and global) can upload automatic enrollment profile Admins and maintainers (team and global) can enable the advanced option to release the device manually from await_device_configured

This is correct (no change from current implementation) for the first one - upload automatic enrollment profile (except that gitops is also allowed to do this, which is probably correct but missing from the spec).

However for enabling the advanced option await_device_configured, this is part of the global app config and the team config, and up until now those settings have always been "writable" only by (global) admins and gitops (not maintainers). That's probably a mistake? Or do we really want to change the permissions for global and team configs?

[mna]

@marko-lisica This dev note mentions:

Add enable_release_device_manually under mdm (Default: false).

But we really want it under mdm.macos_setup.enable_release_device_manually, right?

Also, I assume we need it for the global (no team) kind: config yaml too? It's not shown in the figma.

[marko-lisica]

However for enabling the advanced option await_device_configured, this is part of the global app config and the team config, and up until now those settings have always been "writable" only by (global) admins and gitops (not maintainers). That's probably a mistake? Or do we really want to change the permissions for global and team configs?

As we discussed during the call, solution is outlined in this comment

[mna]

For QA: if the test device gets in a weird state after too many unassign/reassign to MDM server, run sudo profiles renew --type enrollment on the device (if sudo profiles show --type enrollment fails).

[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: https://github.com/fleetdm/fleet/pull/18114

[noahtalerman]

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

PR is here: https://github.com/fleetdm/fleet/pull/18127

[noahtalerman]

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

Docs are in progress. PR is here: https://github.com/fleetdm/fleet/pull/18127

[noahtalerman]

Docs PR is merged! https://github.com/fleetdm/fleet/pull/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: https://github.com/fleetdm/fleet/pull/16728#discussion_r1528899646

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

[noahtalerman]

UPDATE: Doc PR is here: https://github.com/fleetdm/fleet/pull/19225

TODO:

• Update API docs per Martin's comment here: https://github.com/fleetdm/fleet/pull/16728#discussion_r1528899646
• 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.