Add software: custom App Store (VPP) apps

[nonpunctual]

UPDATE: @noahtalerman: Interim solution is in the comment section here: #32461 (comment)

Goal

User story
As an IT admin,
I want to add a custom App Store (VPP) apps in Apple Business Manager and install this app on my Apple (iOS, iPadOS, and macOS) hosts via Fleet
so that I can deploy custom apps to my end users.

Roadmap item

None.

Original requests

None. This issue used to be the request. The original request is in the comment section here: #32461 (comment)

Resources

• Research: Research/Spec: Unlisted app store apps #32713
• https://developer.apple.com/documentation/devicemanagement/generating-developer-tokens

Changes

Product

• UI changes: No changes.
  • The custom App Store (VPP) app shows up on the Software > Add software > App Store (VPP) app alongside all other public App Store apps the IT admin has purchases licenses for in Apple Business Manager (ABM)
• CLI (fleetctl) usage changes: No changes
• YAML changes: No changes.
  • The custom App Store (VPP) app can be added in app_store_apps like all other public App Store apps the IT admin has purchased licenses for in Apple Business Manager (ABM)
• REST API changes: No changes.
  • The custom App Store (VPP) app can be added using the "Add App Store app" API endpoint like all other public App Store apps the IT admin has purchased licenses for in Apple Business Manager (ABM). Custom apps can edited using the "Modify App Store app" API endpoint. Custom apps can be deleted using the "Delete software" API endpoint.
• Fleet's agent (fleetd) changes: No changes
• GitOps mode UI changes: No changes
• GitOps generation changes: No changes
  • When running fleetctl generate-gitops custom App Store (VPP) app are included in app_store_apps like all other public App Store apps the IT admin has purchased licenses for in Apple Business Manager (ABM)
• Activity changes: No changes
  • The custom App Store (VPP) apps generate the same global and host-level activities as all other public App Store apps the IT admin has purchased licenses for in Apple Business Manager (ABM)
    • https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/audit-logs.md#added_app_store_app
    • https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/audit-logs.md#added_app_store_app
    • https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/audit-logs.md#added_app_store_app
    • https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/audit-logs.md#added_app_store_app
    • https://github.com/fleetdm/fleet/blob/main/docs/Contributing/reference/audit-logs.md#added_app_store_app
• Permissions changes: No changes
• Changes to paid features or tiers: Fleet Premium only
• My device and fleetdm.com/better changes: 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

Engineering

• Test plan is finalized

• Contributor API changes: None (existing API endpoints should work)

• Feature guide changes: Update existing VPP guide

  Update /docs/Deploy/app-store-vpp-apps.md (or equivalent) to add:

  ## Custom App Store (VPP) Apps

  Fleet supports deploying custom apps you've added to Apple Business Manager.

  ### Prerequisites
  1. Develop and upload your app to App Store Connect
  2. Add the app to your ABM content location
  3. Purchase licenses for the app in ABM
  4. Connect your VPP token to Fleet

  ### Adding Custom Apps
  Custom apps appear automatically alongside public apps in:
  - Fleet UI: Software > Add software > App Store (VPP)
  - API: Same endpoints as public apps
  - GitOps: Same `app_store_apps` configuration

  ### Troubleshooting
  - **App not showing:** Verify licenses purchased in ABM for your location
  - **Install fails:** Ensure device is supervised and MDM-enrolled
  - **Wrong platform:** Custom apps appear for platforms specified in App Store Connect

• Database schema migrations: None (existing table support custom VPP apps)

• Load testing: Proxy capacity and Apple rate limits

  Concerns:

  1. Apple Enterprise API rate limits - Apple throttles requests per JWT. Single Fleet JWT serving all customers may hit limits under load.
  2. Proxy latency - Additional network hop through fleetdm.com adds ~50-200ms per request
  3. Proxy capacity - fleetdm.com must handle metadata requests from all Fleet Premium instances

Testing needed:

• Simulate n (100+) Fleet instances refreshing VPP app lists concurrently
• Measure Apple API rate limit behavior (429 responses)
• Measure proxy throughput and latency under load
• Verify caching strategy (if implemented) reduces Apple API calls

Mitigation strategies to evaluate:

• Aggressive metadata caching (apps don't change frequently)

• Request batching (combine adam_ids into fewer requests)

• Multiple JWTs if rate limits are per-token

• Load testing/osquery-perf improvements: None (doesn't affect osquery communication or host check-ins)

ℹ️  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.

• Connect a Fleet instance to customer-hawking's test VPP token
• Add, edit, and delete customer-hawking's custom App in Fleet via the UI
• Install customer-hawking`'s custom app on a macOS, iOS, and iPadOS host via Fleet
• Add, edit, and delete customer-hawking's custom App to Fleet via Fleet's API
• Add, edit, and delete customer-hawking's custom App to Fleet via GitOps
• Verify that the new Apple API is used to fetch the version of already added VPP apps every hour. Add the Canva app for macOS and ensure that the version of the VPP app in Fleet matches what is installed on the host and what is available on the App Store.

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]

Moved the original issue description here:

cutomer-hawking has a custom iOS app they developed that is available for distribution in the Apple App Store:

See: https://docs.google.com/document/d/1MveGTMg5Yd50-RziXFaVzCDLWnaUU9ypFe0DTgWnRcM/edit?tab=t.0 for iOS app information

Problem

Fleet can't install this category of app.

What have you tried?

In GetAppStoreApps we skip any app if no iTunes metadata is found. Since Custom Apps don’t show up in the public iTunes API, they get dropped here.
https://github.com/fleetdm/fleet/blob/main/ee/server/service/vpp.go#L250-L254

In AddAppStoreApp we assume iTunes metadata exists. If it’s missing, SupportedDevices is empty and the helper defaults to macOS only, which causes iOS/iPadOS adds to be rejected.
https://github.com/fleetdm/fleet/blob/main/ee/server/service/vpp.go#L384-L394

In getVPPAppsMetadata the loop is over the iTunes metadata map, so if an asset isn’t in that map it never even gets considered.
https://github.com/fleetdm/fleet/blob/main/ee/server/service/vpp.go#L504-L512

The platform helper defaults to macOS when no SupportedDevices are returned, which again hides iOS/iPadOS custom apps.
https://github.com/fleetdm/fleet/blob/main/ee/server/service/vpp.go#L300-L305

I might be missing some context, but it looks like the code is filtering out anything that doesn’t exist in iTunes, even if ABM sent it back as a VPP asset. That would explain why normal Apps & Books apps show up right away, but Custom Apps don’t.

Potential solutions

Allow Fleet to access VPP apps that are not published in the iTunes public App Store metadata.

What is the expected workflow as a result of your proposal?

Customers with their own custom apps would be able to distribute with Apple's App Store capabilities.

[noahtalerman]

@bettapizza no need to add a Gong snippet. We understand the problem.