MDM docs: Add docs for Await Configuration features

[noahtalerman]

UPDATE: This PR has some merge conflicts that we need to resolve before review. Converting to draft.

Two features require workflows that involve Apple's await_device_configured property:

• Populate the Full Name and Account Name during local account creation with the end user's IdP attributes.: Provide populated account creation screen during DEP unboxing #10744
• Require end users to wait for configuration profiles before they can use their new Mac

This PR adds docs for how to accomplish these in Fleet.

[noahtalerman]

Note that there's a decent amount of duplication in this PR. Each feature shares some steps.

I tried to deduplicate by linking the user from one feature to the other but found that this would bounce the user around the page more. I decided not to deduplicate.

[sabrinabuckets]

This is definitely a step in the right direction. I've included some minor corrections and requests for clarity.

Line 348: change "unboxed" to "unboxes"
Line 361: Add comma after "If you haven't already"
Line 363-8: We should add clarity here about what IDPs are supported, and if possible link to instructions for some commonly used. This is a common pain point for admins configuring any kind of SSO/user auth
Line 373: Link appears to be broken, possibly because it's referencing another section on the page but not directly linking to it?
Line 379: Unclear what is meant by "(run custom MDM command)" if it is meant to be an instruction or a link to documentation.
Line 387: Is this pre-supposing that FileVault 2 FDE is not enforced? Because this won't flip to Verifying until the user has interacted.
Line 411-17: Language is duplicative of the previous section, was this intentional? Also the same question about the potentially broken page link.

[noahtalerman]

@sabrinabuckets thanks for the feedback! I addressed your minor tweaks. Comments on bigger changes/questions here:

We should add clarity here about what IDPs are supported, and if possible link to instructions for some commonly used. This is a common pain point for admins configuring any kind of SSO/user auth

All IdPs that support SAML are supported. We call this out in a separate SSO page here: https://fleetdm.com/docs/deploy/single-sign-on-sso#single-sign-on-sso

Line 387: Is this pre-supposing that FileVault 2 FDE is not enforced? Because this won't flip to Verifying until the user has interacted.

Ah, good point. A user has to interact if the Mac is freshly wiped/brand new?

Feedback addressed.

[sabrinabuckets]

@noahtalerman correct, a user always has to interact with turning FV on.

[noahtalerman]

correct, a user always has to interact with turning FV on.

@sabrinabuckets got it. So at this point, disk encryption will show "Action required" right? (not "Verifying")

I updated the docs to reflect this: c11c69c

[zhumo]

Is this the right way to present this step? I don't get a good sense of how I would automate this because it's so clicky. To automate this, I need to set up some server that accepts a signal from Fleet or the host that it's ready to go. Then I need to trigger the command. How do I do that?

[zhumo]

Same with the steps below.

[sabrinabuckets]

Agreed

[noahtalerman]

I don't get a good sense of how I would automate this because it's so clicky.

Great point. I updated the instructions to address this in my latest commits.

I need to set up some server that accepts a signal from Fleet or the host that it's ready to go.

I don't describe setting up a server and how. I think this can be addressed in a later iteration.

What do you think?

[zhumo]

Hi Noah, yeah I don't think we need to tell users how to set up a server, but we should tell them what the interface is between our app and their server.

[noahtalerman]

what the interface is between our app and their server.

For example, the Fleet API? I added this to the instructions.

[noahtalerman]

This PR has some merge conflicts that we need to resolve before review. Converting to draft.

[sabrinabuckets]

I was able to get this configured, but not without help from Roberto. The biggest problem I can see is that we're trying to be too generic with the IdP instructions, and that's just not a recipe for success for the admin trying to configure this.

[noahtalerman]

I was able to get this configured, but not without help from Roberto. The biggest problem I can see is that we're trying to be too generic with the IdP instructions

@sabrinabuckets this part? https://github.com/fleetdm/fleet/pull/14217/files#diff-5477225113c8af2a13747fe4c9bb5c1dd0126cab249a37bad8ae8057e711570eR393-R397

How should we improve it? Did you and Roberto record that call?

[sabrinabuckets]

@noahtalerman yeah, that's the section I'm referring to. As to how to improve it, I can only make a suggestion. IMO the only "right" way to do it is to pick the top 3-5 IdPs we anticipate our customers using, and have someone either document exactly how to configure with each, or at least provide links to the IdP's docs that cover how to do this. For example, with GWS, most of our instructions are entirely unhelpful, as it required creating custom user attributes, and it also requires a specific username convention* that isn't obvious. We didn't record the call, and our efforts were mostly trial & error.

*More on this: this workflow is intended to pre-populate the Full Name and Account Name fields in the macOS user account creation screen. But these don't map 1-1 with any attributes in Google, so through guesswork I came up with these mappings:

using these attributes assigned to my user:

This resulted in both fields being populated with sabrina rather than the actual Full Name. So we were able to verify the mappings work, but not the correct attributes to map. I can't see how we can reasonably expect anyone to figure this out based on our current docs.

Hope that's helpful!

[noahtalerman]

Closing this PR.

These docs will be moved to an article. Currently, Fleet is only making "Quick reference" updates to the docs.

[noahtalerman]

Plan is to move this content to a "macOS Await Configuration" article and link to it from the macOS setup experience page.

This article can be focused using Okta as an IdP. Still TODO