Windows MDM protocol commands

[noahtalerman]

Goal

User story
As an IT admin or Fleet contributor,
I want to send any command supported by the Windows MDM protocol
so that I can manage my Windows devices.

Requirements

• Wipe command is Fleet Premium only. All other commands are available to Fleet Free users.
  • Note that there is no lock command on Windows that behaves like lock on Mac.
• Only maintainers and up can run commands. Team maintainer and team admins can only run commands on hosts assigned to their team.
• IT admin, via CLI/API can send any command supported by Windows MDM protocol
• If a command is sent to an offline host, the command runs when the host comes back online
• IT admin, via CLI/API, can see results for command they sent
• Each time the IT admin sends a command, Fleet sends a push notification to ask the device to check in to the Fleet server
• Windows hosts ask for new commands once per day
• Update error messages for fleetctl query and fleetctl run-script to be consistent with the changes for fleetctl mdm run-command
• The fleetctl get hosts --mdm command returns all hosts, including Windows, that have MDM turned on and use Fleet as their MDM solution.

Changes

Product

• [ ] CLI usage changes: https://www.figma.com/file/6eRuzbDWIUCLPdixIqdmea/%2313069-Windows-MDM-protocol-commands?type=design&node-id=2%3A130&mode=design&t=Dtl0spfdWgG5JFQA-1
• [ ] REST API changes: https://www.figma.com/file/6eRuzbDWIUCLPdixIqdmea/%2313069-Windows-MDM-protocol-commands?type=design&node-id=134-98&mode=design

Engineering

• [ ] Database schema migrations: TODO
• [ ] Documentation changes complete

QA

Manual testing steps

1. ✅ Validate feature is available for both free and paid tenants, specifically:
   • ✅ Validate the Wipe command is not available for free tenants, all other commands are
   • ✅ Validate able to run Wipe command with paid tenant
2. ✅ Validate user roles:
   • ✅ Maintainer and higher, as well as GitOps users can run commands
   • ✅ Observer/+ cannot run commands
   • ✅ Team Maintainer/Admin can only run commands on hosts assigned to their teams
3. ✅ Validate feature is only available via CLI/API, no UI updates at this time
4. ✅ Send test commands and validate results:
   • ✅ Results are returned (reference Figma for success/failure states)
   • ✅ If host is online, command runs when received
   • ✅ If host is offline, command runs when host is back online
5. ✅ Validate no changes made to macOS MDM functionality
6. ✅ Validate fleetctl get hosts --mdm returns results for both macOS and Windows hosts

Confirmation

1. [ ] Engineer (@____): Added comment to user story confirming succesful completion of QA.
2. [ ] QA (@____): Added comment to user story confirming succesful completion of QA.

[noahtalerman]

Hey @marko-lisica I added this story to the product board because you said you're going to have some extra capacity this design sprint.

I haven't filed a story for Windows configuration profiles yet but I will get to that this week.

[noahtalerman]

What is the STATUS if Fleet hasn't sent the command? What about if Fleet send the command but we haven't heard back from the host?

Hey @marcosd4h, follow up to our discussion today, do we get a status code back from the MDM protocol if we haven't heard back from the host?

If we do already, I don't think we need to show a Fleet status like "Pending" in this case.

@marko-lisica found the possible status codes in the Open Mobile Alliance document here (page 86).

[noahtalerman]

• Each time the IT admin sends a command, Fleet sends a push notification to ask the device to check in to the Fleet server
• Windows hosts ask for new commands once per day

Hey @marcosd4h I added the above to the "Requirements" section in this issue following our discussion today. See notes and questions below for more info from our call.

Each time the IT admin sends a command, Fleet sends a push notification to ask the device to check in to the Fleet server

• If a host is offline, it will get 3 push notifications the next time is comes online. This is superior UX. Faster responsiveness. We're ok with performance concerns for now. We can tweak this later.
• Requires no certificate
• Requires configuration on the endpoint. Can we do this automatically
• Requires creating a special Microsoft account.
  • We think Fleet will have to create this account as Fleet the organization (similar to Apple Enterprise Developer program).
  • We want to make sure this requires no extra work on the IT admin's part.
  • We want to make sure that Fleet can create a single account for many customers.

• Windows hosts ask for new commands once per day
• Windows allows you to configure "short polling" and "long polling" intervals
• We can disable short polling
• We can set long polling to once per day. This is relatively arbitrary. We don't need the device to check in often because we're sending push notifications on every command.

[noahtalerman]

cc @marko-lisica @georgekarrv ^

[marcosd4h]

Do we get a status code back from the MDM protocol if we haven't heard back from the host

@noahtalerman The server should handle the case where the host is not available and return a proper status code. The protocol does not handle that AFAIK. On the other hand, when the target host is available, and there is some failure, the protocol should respond with a one the documented status code here

[georgekarrv]

If we built off of the worker package, there is the jobs table available in the db. Additionally we could design another system itself for this.

Jobs could have issues w/ throughput, locks and cron stats.

[noahtalerman]

We think Fleet will have to create this account as Fleet the organization (similar to Apple Enterprise Developer program).

@marcosd4h do you know what kind of account this is? This way, we can file a BizOps request to get some help on this.

Does this look right? https://learn.microsoft.com/en-us/windows/client-management/push-notification-windows-mdm#get-wns-credentials-and-pfn-for-mdm-push-notification

[noahtalerman]

We cut the ability for GitOps uses to run MDM commands. More context here: https://github.com/fleetdm/fleet/issues/13595#issuecomment-1755623534

[noahtalerman]

Learning from @marcosd4h today:

• Fleet is going to get random requests via the MDM protocol (ex. alerts and other chatter) from Windows hosts.
• The Fleet server is required to respond to random requests.
• If the server doesn’t respond, then the host retries a couple times and throws an internal error it's error logs.
• We aren't (we don't) want Fleet to surface these random requests and responses to the IT admin. We only want to surface the the MDM commands (example), and their results, that the IT admin runs.

cc @georgekarrv @gillespi314 @roperzh

[noahtalerman]

Each time the IT admin sends a command, Fleet sends a push notification to ask the device to check in to the Fleet server

@marcosd4h just checking on this requirement.

At some point we discussed that, in order to achieve this, Fleet may have to register w/ Microsoft as an MDM solution. Is this still true?

[marcosd4h]

@noahtalerman, yes, that's correct. MDM relies on Windows Push Notification Services (WNS) to deliver the MDM wake-up call.

The steps to configure this are:

• Fleet has to register a Developer account here
• Then obtain a Package Family Name (PFN) code
• The PFN and the ChannelURI can later be used to send the MDM wake up push notification to the desired system.

The PFN has to be configured on the target device through the DMClient CSP via MS-MDM (Replace Command). Also, the ChannelURI is device-specific and has to be retrieved via MS-MDM too (Get Command)

More details here and here.

FYI @roperzh @mna

[noahtalerman]

@marcosd4h thanks!

The steps to configure this are:

Fleet has to register a Developer account here Then obtain a Package Family Name (PFN) code The PFN and the ChannelURI can later be used to send the MDM wake up push notification to the desired system.

Sounds like we need to do that as part of this story.

cc @georgekarrv

[roperzh]

@sabrinabuckets over-communicating that I merged a fix for the blocking issue so this is ready again.

[sabrinabuckets]

Manual testing steps completed, feature is QA approved for release.

[noahtalerman]

C&C: Pricing page changes are here: https://github.com/fleetdm/fleet/pull/14934/files#diff-f109cc3f7421e05eddf317b7c6cc51395977e63a25dd9eed437985060ed796edR465

TODO Noah: Update this doc page to add Windows. Try to trim extra stuff from the docs.

[fleet-release]

Windows MDM commands, Fleet's touch as light as clouds, Admins' tasks smooth as streams.