Custom URL for Apple (macOS, iOS, iPadOS) MDM features

[noahtalerman]

Goal

User story
As an IT admin working under strict security controls (I don't have control over the Fleet server DNS),
I want to use a different URL, that I control, for the MDM routes in Fleet
so that I can say that the MDM routes don't need a special certificate (mTLS) to communicate w/ Fleet.

Context

• Product designer: @noahtalerman

Original request: #22039

Infrastructure diagram is in a Google doc here (internal).

Changes

Product

• [x] Reference documentation changes: PR is here
• [x] UI changes: Figma wireframes are in Figma here
• [x] CLI (fleetctl) usage changes: No changes.
• [x] YAML changes: YAML files changes are in the PR here
• [x] REST API changes: API changes are in the PR here
• [x] Fleet's agent (fleetd) changes: No changes.
• [x] Activity changes: No changes.
• [x] Permissions changes: Only global admins can update the custom URL for MDM routes.
• [x] Changes to paid features or tiers: Available in Fleet Free and Fleet Premium
• [x] Once shipped, requester has been notified
• [x] Once shipped, dogfooding issue has been filed
  • Issue is here: https://github.com/fleetdm/confidential/issues/8811

Engineering

• [ ] Feature guide changes: Defined in 22710 subtask.
• [x] Database schema migrations: No need
• [x] Load testing: No need

ℹ️  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: High
• Risk description: This change updates MDM URLs in many locations. All MDM functionality should be tested thoroughly using the new URL config to ensure no regressions.

Manual testing steps

• Test setting the config mdm.apple_server_url in gitops/fleetctl apply/env var`
• Configure 2 ngrok tunnels (requires an ngrok upgrade) pointing separate ngrok urls to the same local fleet instance.
• Enroll hosts into Apple MDM, test various MDM functionality, and ensure /mdm/* traffic is only sent to the configured URL
• Not in scope: Changing the URL after MDM is deployed to hosts. A warning message will be added to the UI and documentation stating that MDM devices will need to be re-enrolled if the MDM URL is changed after deployment to hosts.

Testing notes

Completed by @PezHub and confirmed by @xpkoala Confirmed traffic flows via the MDM Server URL for:

• ADE & manual enrollments for Macs
• iPad/iPhone OTA and ADE enrollments
• SSO & Bootstrap pkg installs during setup experience via ADE
• Config profiles pushed to any Apple devices
• Declarations (DDM) are also traveling thru the secondary tunnel :raised_hands::skin-tone-4:
• Windows MDM traffic is still flowing thru the main Fleet App URL by enrolling a WinVM and pushing a few profiles to it.

  Confirmation

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

[Patagonia121]

@noahtalerman I spoke with the customer today and they asked if we could just give them an API option since this is what will unblock them and they said they don't need to wait for a full UX/UI design of the feature. If we focus on enabling this for them, can we accelerate on delivering this for them?

[lukeheath]

@Patagonia121 @harrisonravazzolo Is excluding the MDM enrollment URL from mTLS an option for the customer? That would be the most straight-forward option and not require any change, but it may not be possible with their security policies.

[roperzh]

@lukeheath it's not possible for them, context here: https://fleetdm.slack.com/archives/C04JZ9JQS4U/p1727278806134319

[noahtalerman]

Hey @lukeheath or @georgekarrv, do y'all know what the default URL for MDM clients is?

Is it something like example.fleetdm.com/mdm?

I opened a PR w/ API/YAML design here: https://github.com/fleetdm/fleet/pull/22547

I think we want to show the default value in the docs. Also please let me know if you have thoughts on the UI (Figma here), API, or YAML changes. Thanks!

[wesw-stripe]

@noahtalerman, just wanted to mention that we really only need an API implementation for this and don't necessarily require a UI change. If it's easier that way.

[lukeheath]

@noahtalerman The primary Apple MDM endpoints the agent uses are defined here: https://github.com/fleetdm/fleet/blob/d595881f4ee656a6219e67eab2d5fc5002072ef7/server/mdm/apple/apple_mdm.go#L35-L52

A more exhaustive list looks like this:

macOS MDM Endpoints /mdm/apple/scep: Allows hosts to obtain a SCEP certificate. /mdm/apple/mdm: Allows hosts to reach the server using the MDM protocol. /api/mdm/apple/enroll: If you use automatic enrollment, allows hosts to get an enrollment profile. /api//fleet/device/: Provides end users access to their My device page. /api//fleet/mdm/sso and /api//fleet/mdm/sso/callback: For end user authentication during out-of-the-box macOS setup. /api//fleet/mdm/setup/eula/: For end user agreement to an End User License Agreement (EULA). /api/*/fleet/mdm/bootstrap: Installs a bootstrap package during out-of-the-box macOS setup.

Windows MDM Endpoints /api/mdm/microsoft/management: Allows hosts to get MDM commands and profiles. /api/mdm/microsoft/discovery: Allows hosts to get information from the MDM server. /api/mdm/microsoft/policy: Delivers the enrollment policies required to issue identity certificates to hosts. /api/mdm/microsoft/enroll: Delivers WS-Trust X.509v3 Token Enrollment functionality. /api/mdm/microsoft/tos: Presents end users with the Terms of Service agreement during out-of-the-box Windows setup. /api/mdm/microsoft/auth: Authenticates end users during out-of-the-box Windows setup.

[noahtalerman]

@wesw-stripe got it! Thanks. I like how you're thinking of ways to squeeze this as small as possible #iterate 🟢 https://fleetdm.com/handbook/company#results

[noahtalerman]

Hey @lukeheath, I gave this user story a P2 b/c it's currently blocking customer-starchik's migration to Fleet.

It's not estimated yet.

If Luke agrees that it's P2, @georgekarrv can we do an ad-hoc estimation for this one before we kick off the next sprint?

[noahtalerman]

Hey @sharon-fdm just following up to remind you that this story is in the "Ready to spec" column.

We want to estimate it and bring it into the upcoming sprint.

[sharon-fdm]

@noahtalerman, we have an estimation session attached to today's standup. Will be ready to estimate by then.

[sharon-fdm]

@noahtalerman, we can estimate this with regard to adding new hosts and sending them the newly defined URL. We lack some knowledge about how to update existing hosts. e.g. do we resend the profile to define it for all existing hosts? We are not sure. Maybe @georgekarrv can advise here?

[noahtalerman]

We lack some knowledge about how to update existing hosts. e.g. do we resend the profile to define it for all existing hosts?

@sharon-fdm great question. I'm not sure either.

I'm not even sure if we need to update the URL for existing hosts.

cc @roperzh

[roperzh]

@noahtalerman @sharon-fdm

I think for this to be backwards compatible, and not break anything:

1. We should allow users to only define the base path (this is how the server_settings.server_url config works)
2. If a user has a base path defined, any new enrollment profiles will use this (both for the SCEP URL and the MDM server URL)
3. From 1 and 2, old URLs will continue to work and we shouldn't do anything about them.

Two important notes

1. You can't change the server URL of a host that already turned on MDM
2. I mentioned this to @noahtalerman before: we should do a sanity check both in the server and fleetd that we're not making any assumptions about the MDM server URL being equal to the value configured in server_settings.server_url (I know for sure we do this at least once in fleetd)

[sharon-fdm]

@roperzh, thanks for this elaborated answer.

[mostlikelee]

@noahtalerman are we limiting the scope here to macOS, or Windows MDM as well?

@roperzh is there value in testing this on alternate enrollment methods? I believe we discussed how the enrollment profile is the same regardless of the provisioning method.

[roperzh]

@mostlikelee I think you're right and there's no extra value. All enrollment methods should be covered by smoke tests as well.

[noahtalerman]

are we limiting the scope here to macOS, or Windows MDM as well?

@mostlikelee great question. I'm not sure. I think this depends on whether the customer will run into the same problem when they're migrating Windows.

Using what we know about the customer's infra (diagram here), what do you think?

cc @roperzh

[mostlikelee]

@noahtalerman it looks to be specific to Apple MDM.

@roperzh also pointed out a risk with SCEP renewal. If the MDM URL changes, hosts enrolled under the previous URL may/will not be able to renew the SCEP certificate. Changing the MDM URL after deployment seems like an edge case the requestor doesn't need, so I suggest adding a warning in the API when a user attempts to change it after it's been set. @jacobshandling

[noahtalerman]

it looks to be specific to Apple MDM.

Got it. If that's the case, I think we want to be explicit in the UI/YAML/API. Maybe something like mdm.apple_server_url.

I also agree we should call out the SCEP renewal. That said, I think showing a warning in the API would be too hidden. I think let's show this warning as help text in the UI and document it instead.

Thoughts?

@rachaelshaw and @mostlikelee I added an item to Endpoint ops design review to discuss and review copy updates. I added you to the call.

[weswhet]

@mostlikelee We will most likely need the same support for Windows in the future.

Though that won't be explored till later next year.

[noahtalerman]

Hey @jacobshandling, during yesterday's Endpoint ops design review w/ @mostlikelee and @rachaelshaw we decided to use "Apple" in the new config's name. We landed on mdm.apple_server_url (API/YAML) and "Apple MDM server URL" in the UI:

In addition to the name change, we added some help text copy about the impact of changing this URL (also in the docs here). I also updated the tooltip copy.

Can you please help us make those changes to the UI?

The updated Figma is here.

[noahtalerman]

We will most likely need the same support for Windows in the future.

Though that won't be explored till later next year.

Thanks @weswhet!

In the spirit of iteration, we decided that this story will add support for Apple (macOS, iOS, and iPadOS) hosts.

Later, when y'all are migrating Windows to Fleet, we can decide whether to add a new cross platform config like "MDM server URL" (and deprecate the Apple one) or add a separate config like "Windows MDM server URL"

What do you think?

[weswhet]

@noahtalerman Love it! :shipit:

[jacobshandling]

Roger, thanks @noahtalerman @mostlikelee @rachaelshaw

[jacobshandling]

We landed on mdm.apple_server_url (API/YAML)

@rachaelshaw have we added this update to the API docs?

[rachaelshaw]

@jacobshandling

• https://github.com/fleetdm/fleet/pull/22948
• https://github.com/fleetdm/fleet/pull/22953

[jacobshandling]

@noahtalerman @rachaelshaw what do you think about omitting the parentheses at the end of the tooltip content?

[noahtalerman]

@jacobshandling I dig it! Can you please update Figma too? So the wireframes are consistent w/ what we end up shipping.

[noahtalerman]

Hey @Patagonia121 heads up, this user story shipped in 4.59

[fleet-release]

Custom URL for MDM, Security's diadem. No mTLS gem.