fleet Turn on Windows MDM enroll to Fleet manually using the Settings app

Goal

User story
As an IT admin,
I want my end users on company-owned Windows hosts to turn on MDM and enroll to Fleet using the Settings app
so that I can ensure the end user authenticates using identity provider (IdP) credentials before MDM is turned on and company resources (software, certificates, etc.) are delivered to the host.

Roadmap item

None.

Original requests

#34091

Resources

None.

Changes

Product

[x] UI changes: Figma wireframes
[x] Enroll and turn on MDM: Allow end users on Windows workstations to enroll to Fleet and turn on MDM features by logging in w/ their work credentials (email/password) in Settings > Access work or school.
- Requires the IT admin to connect Fleet to Entra.
- Requires each end user to have at least an Entra P1 license. E3 and E5 licenses work too.
- This means that when an end user enters their credentials, the Window host has MDM turned on and Fleet's agent (fleetd) is delivered.
- The end user's email (username) is collected and used to populated IdP host vitals in Fleet
- Net new hosts will enroll to "No team" in this iteration. If the host is already enrolled to Fleet when the end user enters their credentials, MDM is turned on and the host stays in the team it's already on. The host isn't moved to "No team"
- Set MDM status to "On (manual)" for hosts that turn on MDM via this method.
[x] CLI (fleetctl) usage changes: No changes
[x] YAML changes: https://github.com/fleetdm/fleet/pull/35206
[x] REST API changes: https://github.com/fleetdm/fleet/pull/35206
[x] Fleet's agent (fleetd) changes: No changes
[x] GitOps mode UI changes: No changes
[x] GitOps generation changes: For Fleet Premium only, include enable_turn_on_windows_mdm_manually in the fleetctl generate-gitops output.
[x] Activity changes: No changes.
- Existing mdm_enrolled and fleet_enrolled activities are generated.
[x] Permissions changes: No changes
[x] Changes to paid features or tiers: Fleet Premium only
[x] My device and fleetdm.com/better changes: No changes
[x] Usage statistics: No changes
[x] Other reference documentation changes: No changes
[x] Feature guide changes: https://github.com/fleetdm/fleet/pull/34933
[x] First draft of test plan added
[ ] Once shipped, requester has been notified
[ ] Once shipped, dogfooding issue has been filed

Engineering

[x] Test plan is finalized
[x] Contributor API changes: None
[x] Database schema migrations: Yes ticket added below for adding new config
[x] Load testing: None
[x] Load testing/osquery-perf improvements: None
[x] This is a premium only feature: Yes

ℹ️ Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

Requires load testing: No
Risk level: Low. It won't affect the general case where enrollment is programatic at all, and we'll be updating our integration tests to simulate it

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.

New UI

[ ] In Fleet Premium, verify that you see the new "End user experience section"
[ ] Verify that "Automatic" is selected by default when you toggle "Windows MDM on"
[ ] Verify that if you select "Manual", the "Automatically migrate hosts..." checkbox dissapears.
[ ] In Fleet Free, verify that you only see the toggle
[ ] Verify that if you upgrade from 4.77 w/ Windows MDM turned on, Fleet sets you to the default: "Automatic"

GitOps and API

[ ] In Fleet Premium, verify that you can set enable_turn_on_windows_mdm_manually to true.
[ ] Verify that you see an easy to understand error message if you set enable_turn_on_windows_mdm_manually to true when windows_migration_enabled is already set to true.
[ ] Verify that you see an easy to understand error message if you set windows_migration_enabled when enable_turn_on_windows_mdm_manually is already set to true.
[ ] In Fleet Free, verify that you see an easy to understand error message if you set enable_turn_on_windows_mdm_manually to true.
[ ] Repeat the above steps for the API and verify that you see the same easy to understand error messages.

Enrollment and turning on MDM

[ ] Turn on Windows MDM in Fleet and select "Manual" for "End user experience"
[ ] Follow step 1 and 2 in the "Automatic enrollment" section of the updated "Windows MDM setup" guide to connect Fleet to Entra and purchase the necessary licenses
[ ] Also, connect Entra to Okta to require end users to authenticate w/ Okta when they turn on MDM via Settings > Access work or school.
[ ] On a Windows host that doesn't have Fleet's agent (not enrolled to Fleet), follow these instructions to enroll to Fleet.
- [ ] Verify that the host is enrolled to Fleet (agent is installed), added to "No team", and MDM is turned on
- [ ] Verify that the end user isn't prompted by Fleet to authenticate w/ IdP credentials if "No team" has end user authentication disabled.
  - If end user authentication is enabled, then we expect the end user to get prompted by Fleet to authenticate w/ IdP credentials (double-auth).
    - In this scenario, verify that Fleet sets the IdP username to the username used during the second authentication.
- [ ] Verify that the host has MDM status set to "On (manual)" and is added to the list of hosts w/ "On (manual)" on the dashboard and Host page
- [ ] Verify that the host's IdP host vitals are populated using the email (username) you entered in Access work or school unless end user authentication is enabled for "No team"
- [ ] Verify that Windows configuration profiles are delivered to the host
[ ] pingali scenario: On a Windows host that already has Fleet's agent (enrolled to Fleet) and is assigned to a team other than "No team", follow these instructions.
- [ ] Verify that the host stays enrolled to Fleet but isn't moved to "No team"
- [ ] Verify that the host has MDM status set to "On (manual)" and is added to the list of hosts w/ "On (manual)" on the dashboard and Host page
- [ ] Verify that the host's IdP host vitals are populated using the email (username) you entered
- [ ] Verify that Windows configuration profiles are delivered to the host

Migration

[x] Add the migration policy + script to Fleet
- [ ] Verify that the policy fails and triggers the script if MDM is off.
- [ ] Verify that the script opens a native Windows window that looks like the following:
  - [ ] The window has this title: "Migrate to Fleet"
  - [ ] The windows has this description:
    - First line: Close this window, go to Settings and search "Access work or school"
    - Second line: Select Connect and enter your work email and password.
    - Third line: This Migrate to Fleet window will popup every 5 minutes until you finish.
    - "Access work or school" is in quotes. Connect and Migrate to Fleet are bold.
[ ] Verify that when you close the windows, it comes back in 5 minutes
[ ] Verify that you can close the window and complete the steps to turn on MDM.
[ ] Verify that the window doesn't pop back up after you complete the steps and turn on MDM

Testing notes

Confirmation

[ ] Engineer: Added comment to user story confirming successful completion of test plan.
[ ] QA: Added comment to user story confirming successful completion of test plan.

Oct 09 '25 14:10 noahtalerman

FYI @georgekarrv I forgot about this story when we T-shirt sized on Friday (2025-10-10).

I added it to 4.78 for now. Please let me know if you have any questions/concerns.

Oct 13 '25 20:10 noahtalerman

@noahtalerman I would use SyncMLViewer to track traffic from the MDM server and from the client to the MDM server, while enrolling via the Settings app on the Windows host. This way, you can check if the email is available in any of the SyncML messages sent to the server.

Oct 16 '25 17:10 marko-lisica

I see this error when I entered my Microsoft username and password in Settings > Access work or school.

Tried this flow w/ and w/o fleetd installed.

Also, no messages showing up in SyncML Viewer.

Tried this flow w/ and w/o fleetd installed.

Oct 25 '25 18:10 noahtalerman

I see this error when I entered my Microsoft username and password in Settings > Access work or school.

Tried this flow w/ and w/o fleetd installed.

Also, no messages showing up in SyncML Viewer.

Hey @JordanMontgomery any idea what this 400 response means? Did we get any help logs/error messages in the Fleet server?

This story tracks adding support for this Windows enrollment method. I tried the flow to test if Fleet today already supported this enrollment method.

Oct 28 '25 14:10 noahtalerman

@noahtalerman I don't see anything obvious in the logs here but it's hard to be sure exactly what we're looking for unfortunately. This may be easier to test if done against a local fleet instance just so there is less "noise" from other devices

Oct 29 '25 18:10 JordanMontgomery

Update the "On (manual)" tooltip copy on the dashboard, Hosts page, and Host details page to the following: "MDM was turned on manually. End users can turn MDM off."

Opened a PR for the above copy change: https://github.com/fleetdm/fleet/pull/35048

Removed this from the test plan:

[ ] Verify that the tooltip copy for "On (manual)" is updated on the dashboard, Hosts page, and Host details page. See "Change" section for expected copy.

FYI @getvictor @AndreyKizimenko

Oct 31 '25 13:10 noahtalerman

UPDATE: Request is here:

https://github.com/fleetdm/confidential/issues/12925

DONE: @noahtalerman: Separate story that goes to :help-customers for this:

[x] Migration policy + script:

Write a policy that checks if a Windows workstation has MDM turned on. The policy fails if MDM is off. Put this policy in the docs/solutions/Windows/ folder in the repo.

Write a PowerShell script that starts a scheduled job to open a native Windows notification to nudge the end user to turn on MDM. The scheduled job runs every 5 minutes and stops once MDM is turned on. Put this script in the docs/solutions/Windows/ folder in the repo.

The window has this title: "Migrate to Fleet"

The windows has this description:

First line: Close this window, go to Settings and search "Access work or school"

Second line: Select Connect and enter your work email and password.

Third line: This Migrate to Fleet window will popup every 5 minutes until you finish.

"Access work or school" is in quotes. Connect and Migrate to Fleet are bold.

Nov 05 '25 16:11 noahtalerman

@JordanMontgomery for testing during spec'ing:

This means that when an end user enters their credentials, the Window host has MDM turned on and Fleet's agent (fleetd) is delivered.

Does this already happen?

The end user's email (username) is collected and used to populated IdP host vitals in Fleet

Do we get anything that allows Fleet to collect the IdP username? Is it included in any Windows MDM protocol messages?

Net new hosts will enroll to "No team" in this iteration. If the host is already enrolled to Fleet when the end user enters their credentials, MDM is turned on and the host stays in the team it's already on. The host isn't moved to "No team"

Can installing fleetd on a host that's already enrolled to Fleet flip it's team?

Nov 05 '25 16:11 noahtalerman

@noahtalerman

Does this already happen? Can installing fleetd on a host that's already enrolled to Fleet flip it's team?

Yes it appears it does happen(fleetd gets installed if not) and as far as I can tell, no it does not flip its team. I have successfully enrolled a host with and without fleet already installed via the settings page: With fleetd already installed it stayed in the team. Without Fleetd installed it went to "no team" and installed fleetd

Do we get anything that allows Fleet to collect the IdP username? Is it included in any Windows MDM protocol messages?

Yes it looks like we get the UPN of the user which should be their email. After some digging I also found we get "NotInOOBE"=true/false which true means we are Not in OOBE(i.e. they enrolled via Settings) and true means we are in OOBE(i.e. autopilot) which we can use to determine manual or automatic enrollment status

Nov 06 '25 21:11 JordanMontgomery

Yes it appears it does happen(fleetd gets installed if not) and as far as I can tell, no it does not flip its team. I have successfully enrolled a host with and without fleet already installed via the settings page: With fleetd already installed it stayed in the team. Without Fleetd installed it went to "no team" and installed fleetd

Sweet!

Yes it looks like we get the UPN of the user which should be their email. After some digging I also found we get "NotInOOBE"=true/false which true means we are Not in OOBE(i.e. they enrolled via Settings) and true means we are in OOBE(i.e. autopilot) which we can use to determine manual or automatic enrollment status

Baller!

Ty @JordanMontgomery

Nov 06 '25 22:11 noahtalerman

Engineering QA

Risk assessment

Requires load testing: No
Risk level: Low. It won't affect the general case where enrollment is programatic at all, and we'll be updating our integration tests to simulate it