iOS/iPadOS Install software and offer self-service software for Account-based User Enrolled hosts

[marko-lisica]

Goal

User story
As an IT admin,
I want to install VPP and in-house (.ipa) apps on iOS and iPadOS hosts that enrolled via Account-based User Enrollment with Managed Apple Account(also via self-service).

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes.
• YAML changes: No changes.
• REST API changes:
  • User should be able to install apps on the user-enrolled hosts. Currently, Fleet throws this error: Couldn't install. Currently, software install isn't supported on personal (BYOD) iOS and iPadOS hosts.
• Fleet's agent (fleetd) changes: No changes.
• Fleet server configuration changes: No changes.
• Exposed, public API endpoint changes: No changes.
• fleetdm.com changes: No changes.
• GitOps mode UI changes: No changes.
• GitOps generation changes: No changes.
• Activity changes: No changes.
• Permissions changes: No changes.
• Changes to paid features or tiers: Available in Fleet Premium.
• My device and fleetdm.com/better changes:
  • Enable self-service for user-enrolled hosts. Currently, Fleet shows that it's not available.
• Usage statistics: 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. Dogfood: iOS/iPadOS Install software and offer self-service software for Account-based User Enrolled hosts #46635

Engineering

• Test plan is finalized
• Contributor API changes: No changes
• Feature guide changes: [Guide] iOS/iPadOS Install software and offer self-service software for account-based user enrolled hosts #42709
• Database schema migrations:

1. vpp_client_users table (sub-issue BAI: Schema for VPP client-user mapping #43999) — maps (vpp_token_id, managed_apple_id) to the Fleet-generated client_user_id and Apple's returned
   apple_user_id. Columns: id, vpp_token_id (FK to vpp_tokens.id ON DELETE CASCADE), managed_apple_id VARCHAR(255), client_user_id VARCHAR(36), apple_user_id
   VARCHAR(255) NULL, status ENUM('pending','registered','retired'), timestamps. Unique constraints on (vpp_token_id, managed_apple_id) and (vpp_token_id,
   client_user_id).
2. host_mdm.managed_apple_id column (sub-issue BAI: Surface Managed Apple ID for user-enrolled hosts #44001) — ALTER TABLE host_mdm ADD COLUMN managed_apple_id VARCHAR(255) NULL AFTER fleet_enroll_ref. Populated
   from nanomdm's TokenUpdate hook at user-enrollment completion. Confirmed: no managed_apple_id column exists on host_mdm today.

• This is a premium only feature: Yes

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

Risk assessment

• Requires testing in a hosted environment: Yes

• Risk level: High

• Risk description:

• (1) Silent failure mode: Today Fleet sends serialNumbers for user-enrolled hosts and Apple doesn't error but installs silently fail — if the new clientUserIds flow has a bug, the failure could be similarly invisible.

• (2) Apple API dependency: VPP user-creation and user-scoped asset-association semantics can't be fully validated outside Apple's production environment (sandbox may differ).

• (3) InstallApplication refactoring touches every VPP + .ipa install send path; this is the same refactor iOS/iPadOS apps: Managed app configuration #38790 needs (IOSMAC: Inject Configuration dict into Apple InstallApplication command #43966/BAI: InstallApplication command shape for user-enrolled hosts #44005 overlap).

• (4) Gate ordering: BAI: Remove BYOD install gates and add enrollment-aware install path #43998 (removing the BYOD block) must land last. If it merges before dependencies are complete, installs break silently instead of showing a clear error.

• (5) License accounting: user-license semantics (up to 5 devices per license) differ from device-license semantics and need empirical verification against Apple's API.

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.

Core flow

• Make sure that the user can install all iOS/iPadOS apps that are available on the team (including .ipa) on user-enrolled hosts.
• Make sure that the user can install apps via API on user-enrolled hosts.
• Make sure the flow is the same for both manually enrolled iOS/iPadOS and user-enrolled iOS/iPadOS. User purchases a license and assigns it to the location (VPP token) that is added to Fleet, then the user can see those apps when adding software to the team.
• Make sure that end users can use self-service on user-enrolled hosts.
• Make sure that the setup experience software selected for the iOS and iPadOS hosts installs automatically on enrollment for user-enrolled hosts.

UI

• Verify that all UI changes specified in the Figma wireframes are correctly implemented
• Verify expected UI states (loading, empty, error states if applicable)

API

• Test all API endpoints added or modified in the API changes section of this issue
• Verify error handling for invalid inputs where applicable

GitOps (generate + run)

• Configure the feature through the UI and run fleetctl generate-gitops
• Confirm the generated .yml includes the expected fields (compare with YAML changes in the Product section)
• Modify the generated .yml and run fleetctl gitops
• Confirm the configuration updates correctly in Fleet
• Enable GitOps mode and verify the feature behaves correctly

Permissions

• Verify role restrictions are applied correctly for global roles
• Verify role restrictions are applied correctly for fleet-level roles

Edge cases

• App already installed by end user before Fleet sends install (Apple returns "already installed" error)
• Host with no Managed Apple ID available (incomplete enrollment data)
• VPP token with 0 available licenses for user-enrolled host
• User license at the 5-device-per-user limit
• Multiple VPP locations for the same Managed Apple ID — which token is selected?
• Mixed fleet: manually-enrolled + user-enrolled hosts for the same app (regression check)
• .ipa in-house package install on a user-enrolled host
• User unenrolls then re-enrolls — VPP client user row should be reused, not duplicated

Supplemental testing

Testing notes

Confirmation

1. Engineer: Added comment to user story confirming successful completion of test plan (include any special setup, test data, or configuration used during development/testing if applicable).
2. QA: Added comment to user story confirming successful completion of test plan.

[JordanMontgomery]

Some notes from my experimentation with this:

Once a user is created and associated to a managed apple ID our existing vpp.AssociateAssets call can associate those assets with users(as opposed to just devices) by using the clientUserIds parameter. Apple will apparently allow us to pass enrollmentIds as SerialNumbers in that request which our code is errantly doing today and while this does not result in an error a device with a User Enrollment cannot install the VPP app afterward, so we must use the user ID and associate that with the token.

We should look into if there are any complicating factors if a user is associated with multiple Locations. We should also determine if our licensing logic works properly in this scenario - user licensing has different rules(I saw references to "up to 5 devices" for instance).

We likely also want to remove ChangeManagementState from our install command for User Enrollments because Apple docs suggest it is not supported here.

We may want to use different ManagementFlags as well, or we may not need to. ManagementFlags=1 means the app gets removed when the enrollment gets removed which sounds right for user enrollment but we may not even need to do that as the User Enrollment verbiage already says that, so it may just be the default, unavoidable behavior