macOS setup experience: setup Platform SSO to create local user account with IdP credentials

[marko-lisica]

UPDATE: @gillespi314: FYI draft PR #34096 has a report on PoC results (tl;dr we implemented the simplified flow to install the PSSO app and confirmed that final portions of the flow are still not fully supported by Entra/Company Portal; time box did not allow us to test Okta directly, but signs point to the same issue there)

---

Goal

User story
As an IT admin,
I want to make sure Platform SSO is set up during Setup Assistant when setting up (ADE) new Mac (Tahoe)
so that my end users can use the same credentials to log in to their Mac.

Roadmap item

None.

Original requests

#27960

Context

• Product Designer: @marko-lisica
• Engineering DRI: @georgekarrv

Changes

Product

• UI changes: Figma file
• CLI (fleetctl) usage changes: No changes.
• YAML changes: [API/YAML] macOS setup experience: setup Platform SSO to create local user account with IdP credentials #33262
• REST API changes: [API/YAML] macOS setup experience: setup Platform SSO to create local user account with IdP credentials #33262
• Fleet's agent (fleetd) changes: No changes.
• GitOps mode UI changes: Specified in Figma above.
• GitOps generation changes: Export controls.macos_setup.create_local_user_account and subkeys with fleetctl generate-gitops.
• Activity changes: [Activity] macOS setup experience: setup Platform SSO to create local user account with IdP credentials #33263
• Permissions changes: Global and team admin, maintainer, and GitOps. Covered by "Edit macOS setup experience" row in permissions.
• Changes to paid features or tiers: Fleet Premium
• My device and fleetdm.com/better changes: No changes.
• Other reference documentation changes: No changes.
• First draft of test plan added
• Once shipped, requester has been notified
• Once shipped, dogfooding issue has been filed

Engineering

• Test plan is finalized
• Contributor API changes: TODO
• Feature guide changes: TODO
• 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

Test plan

Make sure to go through the list and consider all events that might be related to this story, so we catch edge cases earlier.

UI

• Make sure that new Create local user account on macOS option is available on Controls > Setup Experience > End user authentication page.
• Verify that Create local user account on macOS is disabled if user haven't selected Turn on end user authentication, and the tooltip shows over the disabled checkbox.
• Verify that the copy is updated for the empty state on End user authentication page, when IdP isn't configured.
• Verify that when the user enables Create local user account on macOS option, the configuration profile and software dropdowns appear.
• Verify that the user can search for both software and configuration profile when the dropdown menu is open.
• Verify that in the software dropdown only packages are listed, not VPP apps.
• Verify that the user can't Save if the software and configuration profile aren't selected.
• Make sure that Fleet validates the selected configuration profile on save, and it reject profile that is not com.apple.extensiblesso or ones that are missing EnableRegistrationDuringSetup field.
• Make sure that Fleet displays an error if the user selects software (package) on End user authentication page that is already selected on the Setup experience > Software install page.
• Verify that global activities are generated when the user check/uncheck Turn on end user authentication and that the copy is updated.
• Verify that global activities are generated when the user check/uncheck Create local user account and copy is as specified in Figma.
• Make sure that the UI above is disabled if GitOps mode is enabled, as specified in Figma.
• Make sure that automatic local user account creation works even if the configuration profile and software specified aren't in scope for the macOS host that is enrolling (labels defined on the software and profile level shouldn't apply for this feature).
• Verify that the user gets an error if they try to delete a configuration profile on the Controls > OS settings > Custom settings page, which is selected for automatic local user account creation.
• Verify that the user gets an error if they try to delete a software (package), which is selected for automatic local user account creation.
• Verify that the user gets an error if they try to select a setup experience software, which is selected for automatic local user account creation.
• Verify that the user can log in to macOS if the Platform SSO profile is deleted from host.
• Verify that the user can log in to macOS if the SSO extension software is deleted from host.

Setup experience

• Verify that if Turn on end user authentication and Create local user account on macOS are checked (SSO profile and software selected), then the end user is asked to authenticate with IdP, and the local user account is created automatically with IdP credentials.
• Verify that if Turn on end user authentication and Create local user account on macOS are checked (SSO profile and software selected), but the host isn't running macOS 26 (Tahoe) , then end user is asked to authenticate with IdP, and the local user account information is populated, but user needs to provide a password (existing behavior).
• Verify that if only Turn on end user authentication is checked, then the end user is asked to authenticate with IdP, and the local user account information is populated, but the user needs to provide a password (existing behavior), on hosts running macOS 26 and below.
• Make sure that this feature works when the setup experience software/scripts is enabled and disabled, and when the bootstrap package is enabled and disabled, and when the user customizes the Setup Assistant with a profile.

GitOps

• Make sure that the user can enable automatic local user account creation via YAML using controls.macos_setup.create_local_user_account.
• Verify that Fleet returns errors specified here: PR comment link
• Make sure to export controls.macos_setup.create_local_user_account and subkeys with fleetctl generate-gitops

API

• Make sure that the user can enable automatic local user account creation via API, using PATCH /api/v1/fleet/setup_experience
• Verify that Fleet returns errors specified here: PR comment link

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan.
2. QA: Added comment to user story confirming successful completion of test plan.

[ddribeiro]

Hey @noahtalerman, this came up during today's call with numa. Do you know if Fleet will support this out of the box when Tahoe releases or will it require product work?

numa is considering us supporting this feature when Tahoe releases as part of our commitment to same day support.