Enroll personally owned (BYOD) iOS/iPadOS devices with work email (Managed Apple Account)

[marko-lisica]

Goal

User story
As an IT admin,
I want my end users to enroll their personal iPhones and iPads through the Settings app by signing in with my work email (same as IdP)
so that I can enforce settings necessary to access organization resources/tools.

Key result

Account-based user enrollment for personal Apple devices (BYOD)

Original requests

• #19329

Context

• Product Designer: @marko-lisica

Changes

Product

• [x] UI changes: Figma link
• [x] CLI (fleetctl) usage changes: No changes.
• [x] YAML changes: #30176
• [x] REST API changes: #30176
• [x] Fleet's agent (fleetd) changes: No changes.
• [x] GitOps mode changes: Changes specified in Figma link above.
• [x] Activity changes: #30186
• [ ] Permissions changes: TODO
• [x] Changes to paid features or tiers: Fleet Premium only (requires ABM integration)
• [ ] Transparency changes: TODO
• [ ] First draft of test plan added
• [ ] Other reference documentation changes: No changes.
• [ ] Once shipped, requester has been notified
• [ ] Once shipped, dogfooding issue has been filed

Engineering

• [ ] Test plan is finalized
• [ ] Contributor API changes: Specified in #30176
• [ ] 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.

1. Step 1
2. Step 2
3. Step 3

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.

[noahtalerman]

FYI @marko-lisica, for when we get to drafting this story, Mike McNeil has this though which I think is a great idea:

For account based user enrollment, let’s get Mike T’s help on end user /enroll page. Why? Better employee experience is core to Fleet.

[alexmitchelliii]

@noahtalerman @marko-lisica to make this user story valuable, we should also complete issues related to user scope payload.

[marko-lisica]

Hey @georgekarrv, heads up, this story is ready to spec.

[marko-lisica]

Based on our discussion during design review, I just updated scope of this story to exclude VPP app install. I filled a separate story: #31138. We initially thought that this functionality will be available out of the box, but it turned out that we need to do a lot of additional work to tie users to VPP token and assign licenses to users instead of devices via Apps and Books API.

@ghernandez345 There are updates for software tab on host details for personal hosts. See Figma here. Btw. inventory/library tabs are added by #g-software team.

I updated test plan as well.

cc @georgekarrv @JordanMontgomery

[PezHub]

QA test results - 1st pass:

• [x] ABM workflow succeeds and iPhone enrolls in Fleet with expected UI details

Empty state when MDM is off -

API Testing -

• [x] Confirmed the endpoint /api/v1/fleet/hosts/summary/mdm returns the new status count: enrolled_personal_hosts_count

{
  "counts_updated_at": "2025-07-31T00:13:09Z",
  "mobile_device_management_enrollment_status": {
    "enrolled_manual_hosts_count": 3,
    "enrolled_automated_hosts_count": 0,
    "enrolled_personal_hosts_count": 1,
    "pending_hosts_count": 0,
    "unenrolled_hosts_count": 1,
    "hosts_count": 5
  },
  "mobile_device_management_solution": [
    {
      "id": 1,
      "name": "Fleet",
      "server_url": "https://pezhub.ngrok.app/mdm/apple/mdm",
      "hosts_count": 1
    },
    {
      "id": 43,
      "name": "Fleet",
      "server_url": "https://pezhub.ngrok.app/api/mdm/microsoft/discovery",
      "hosts_count": 2
    },
    {
      "id": 100,
      "name": "Fleet",
      "server_url": "https://pezhub.ngrok.app",
      "hosts_count": 1
    }
  ]
}

Other -

• [x] I see the expected error when trying to enroll a macOS host

[PezHub]

Filed a few unreleased bugs -

• https://github.com/fleetdm/fleet/issues/31450
• https://github.com/fleetdm/fleet/issues/31457
• https://github.com/fleetdm/fleet/issues/31329

[PezHub]

Learn if OS updates work out-of-the-box on BYOD hosts.

Unfortunately they don't. I added an ADE enrolled iPad and BYOD iphone to the same team with the same OS update settings configured and the iPhone never received the notification while the iPad did. I also tested a BYOD host that was not enrolled with a managed AppleID and it did get the notification. So it's just limited to account-driven enrollments.

Learn what happens with BYOD hosts if the user deletes the ABM token.

I did not see any adverse effects. The enrollment profile remained on the host and mdm status stayed ON

@marko-lisica ^^^

[marko-lisica]

Unfortunately they don't. I added an ADE enrolled iPad and BYOD iphone to the same team with the same OS update settings configured and the iPhone never received the notification while the iPad did. I also tested a BYOD host that was not enrolled with a managed AppleID and it did get the notification. So it's just limited to account-driven enrollments.

Thanks @PezHub! Actually, it's documented here that it's not supported in user enrollment.

[PezHub]

Load Testing Results, 1st Pass -

Setup:

• Total of 5k hosts; 500 iPads, 500 iPhones
• I manipulated the DB to change all the osquery_perf mobile hosts to is_personal_enrollment = '1' in the hosts_mdm table to simulate Account-driven user enrolled hosts
• ran a few queries and verified performance was good and confirmed the aggregate counts update accordingly when making additional changes

e.g

SELECT COUNT(*) FROM host_mdm
WHERE enrollment_status = 'on (personal)';

[PezHub]

Load Testing Results, 2nd Pass -

• increased the total host count to 10K+ with over 2,000 mobile devices
• query results remained performant @ 126ms

SELECT COUNT(*) AS count_personal_enrollments
FROM host_mdm
WHERE is_personal_enrollment = '1';

• UI counts look accurate as well

[AndreyKizimenko]

Confirmed that Enabling .well-known resource still lets BYOD devices to enroll successfully and get marked as personal within MDM status All of the remaining issues has been confirmed as fixed, moving this story into Ready for Release

[noahtalerman]

Confirm and celebrate:

• @noahtalerman: Looks like we forgot to update the audit logs page: https://github.com/fleetdm/fleet/pull/30186#issuecomment-3210758744

Waiting to close this story out until we confirm.

cc @ghernandez345 @marko-lisica

[marko-lisica]

@JordanMontgomery, do you know if we added fields from PR to activities?

[noahtalerman]

Confirm and celebrate:

• @noahtalerman: Looks like we forgot to update the audit logs page: https://github.com/fleetdm/fleet/pull/30186#issuecomment-3210758744

Waiting to close this story out until we confirm.

@JordanMontgomery, do you know if we added fields from PR to activities?

Hey @JordanMontgomery just giving you another ping!

[noahtalerman]

• @noahtalerman: Looks like we forgot to update the audit logs page: https://github.com/fleetdm/fleet/pull/30186#issuecomment-3210758744

UPDATE: @noahtalerman: We decided to add enrollment_id. We decided not to add personal_host (PR here). enrollment_id which is null except for personal enrollments where it has a value.

More info in this PR: https://github.com/fleetdm/fleet/pull/30186

[fleet-release]

Personal device connect, Work data kept separate, Fleet's touch, light and deft.