Install Apple App Store apps on macOS

[noahtalerman]

Goal

User story
As an IT admin,
I want to install Apple App Store apps on my macOS hosts
so that I can give my end user's access to software that my organization ordered for them in Apple Business Manager (ex. Xcode).

Context

• Requestor(s): @mikermcneil
• Product designer: @marko-lisica

This story requires connecting Fleet to Apple's Volume Purchasing Program (VPP)

This is user story applies to this Fleet Q2 OKR:

• Increase product maturity and fulfill customer promises

Changes

Product

• UI changes: Figma link
• CLI usage changes: Figma link
• REST API changes: API design: Install Apple App Store apps on macOS #19291
• Permissions changes:
  • Maintainers and admins (team and global) can view, add, and delete VPP software. GitOps user can manage VPP software via Fleet YAML. (Team roles can do specified actions to software added to their team(s) and can add VPP software to teams they are assigned to.)
  • Maintainers and admins (team and global) can install VPP software on a specific host. (Team roles can do install VPP software on hosts assigned to their team(s))
  • Observers (team and global) can view VPP software (Team observers can view only VPP software added to their team(s).)
  • Fleet admin (global) can enable VPP, disable VPP, renew VPP token.
• Outdated documentation changes:
  • Document VPP integration steps and how to add and install VPP software. Write an article on how to enable VPP (consider account password change), how to find App Store ID
  • GitOps reference docs: GitOps docs: Install software #20502
• Changes to paid features or tiers: Available in Fleet Premium
• Other requirements:
  • GET /api/v1/fleet/software/app_store_apps checks for available purchased app in ABM and pulls metadata for each app (name, latestVersionInfo and bundleId ) and returns the list of available apps.
    • It shouldn't return an app that's already added to a team. (e.g. If user added Pages app to a team, next time when hit this API for that team Logic Pro shouldn't be returned since it's already added to software title
    • If VPP app is removed from software title, it should be available in this API again.
    • List apps that have macOS in supportedPlatforms and productType is App
  • Adding VPP app via POST /api/v1/fleet/software/app_store_apps/:app_store_id uses app_store_id of VPP app.
    • First associate license to a host. If not available throw an error (install can't happen)
    • If license is associated successfully, then send MDM command to install VPP app.
  • When disabling VPP (DELETE /api/v1/fleet/mdm/apple/vpp_token) we want to delete content token (.vpptoken) from database. All activities associated with VPP apps should remain.
  • For VPP apps POST /api/v1/fleet/hosts/:id/software/install/:software_title_id should first assign license to the host (using Apple API), if Apple returns an error, we'll throw a generic error message, except in 2 cases: when we get the error that there are no enough licenses and when VPP token is expired.
    • After license was successfully assigned (we got success from Apple), send InstallApplication MDM command, using this temaplate.
  • GET /api/v1/fleet/hosts/:idd/software should return "package_available_for_install": "" for App Store app

Engineering

• 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

• Risk level: Low

Manual testing steps

Prerequisites -

• VPP token shared in 1Password

VPP Integration

• Verify new VPP tab is available on the Settings/Integrations page
• Ensure Turn on MDM link works for new setups
• When/if MDM is turned on, ensure ENABLE button works
• Verify all copy matches Figma
• Download VPP Token from ABM, upload to Fleet
• Ensure file type validation is working. Verify errors against copy in Figma
• Upon successful upload, ensure green toast message and new copy
• Click EDIT and ensure disable and renew functionality
• Go thru entire Renewal workflow
• Under software titles page in UI, verify VPP apps are listed, check against Figma
• Add software modal should have a new tab for VPP
• Ensure spinner appears when adding/waiting for VPP list to populate
• Validate empty state
• Validate list matches ABM
• Validate errors match Figma
• Ensure error toast if title already exists

Software Title Details page

• Logo from app store displays
• Self Service Tag is present when enabled
• Test Actions -> Delete
• Ensure app name gets updated after OS Query runs
• Verify API has new app_store object

Host details Software page

• Actions -> install = ensure apps are installing via mdm commands
• Verify loading state
• Verify successes and failures against Figma copy

Activity Feed

• Verify host activity feed
• Verify Global activity feed

Test GitOps workflow

• Yaml config file

Test API

• Functionality
• verify Errors

Other Considerations

• iOS (future support) vs macOS version displayed?
• License counts displayed?
• What happens when a license is revoked?
• What happens when you exceed license count?

Testing notes

Confirmation

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

[noahtalerman]

Hey @lukeheath, do you have admin (create user) access in Fleet's Apple Business Manager account?

If yes, can you please create an account for @marko-lisica? That way, Marko can do some research on how we would purchases licenses in ABM.

[lukeheath]

@marko-lisica @noahtalerman Done! You should receive an email.

I've also made @georgekarrv an ABM admin so he can help manage the instance.

[marko-lisica]

Hey @lukeheath, I didn't get the email yet. Can you or @georgekarrv try to add me again?

[georgekarrv]

I'll take a look here in ~5m

[georgekarrv]

Should be sent now

[marko-lisica]

Hey @georgekarrv , heads up the story is ready to be specified.

[noahtalerman]

Hey @marko-lisica just checking, do we want “software” in the activity feed copy? (first item in screenshot below)

I see we’re using "software" for App Store apps but not custom packages. Is that intentional?

[marko-lisica]

Hey @marko-lisica just checking, do we want “software” in the activity feed copy? (first item in screenshot below)
I see we’re using "software" for App Store apps but not custom packages. Is that intentional?

@noahtalerman Thanks for catching this. It was a mistake since we decided to cut the and software from activities related to both VPP and custom software packages.

[PezHub]

QA Notes:

• See list of items above that were tested and not tested (for various reasons e.g future enhancements).
• spent a good deal of time on the UI and worked out a few UI bugs with the team
• spent less time testing API and GitOps functionality due to limited time and resources, but basic tests pass.

Over all things are looking great!

[noahtalerman]

Hey @Patagonia121 and @dherder heads up that this customer/prospect request was shipped in Fleet 4.55.

Heads up that we marked the feature as experimental. Here's what that means: https://fleetdm.com/handbook/company/product-groups#experimental-features

PR to call this out in the API docs is here: #21379

UDPATE: The above PR is merged! (@noahtalerman)

@marko-lisica I passed this issue to you. Can you please close this issue once the PR is merged? Thanks :)

[fleet-release]

Apps from the cloud,
Ease for admins bestowed,
Work flows as water.