macOS local admin account: Rotate password

[noahtalerman]

Goal

User story
As an IT admin that used a local admin account for troubleshooting,
I want Fleet to rotate the account's password
so that I can be confident admin credentials aren't leaked.

Changes

Product

• UI changes: Figma
• CLI (fleetctl) usage changes: No changes
• YAML changes: No changes
• REST API changes:
  • [API] updates for local admin account: Rotate password #42722
  • Update - [API] Fix endpoint naming for rotating managed account password #44827
  • Error messages:
    • rotation in progress: Managed local account password rotation is already in progress for this host.
    • rotation pending: Cannot rotate managed local account password while an operation is pending.
    • other/unknown/general: Couldn’t rotate managed local account password. Please try again.
• Fleet's agent (fleetd) changes: No changes
• GitOps mode UI changes: No changes
• GitOps generation changes: No changes
• Activity changes: [Activity] updates for local admin account: Rotate password #42724
  • Type name: Rotated managed local account password
• Permissions changes: No changes
• Changes to paid features or tiers: No changes
• My device and fleetdm.com/better changes: No changes
• Usage statistics: No changes
• Other reference documentation changes: No changes
• First draft of test plan added
• Once shipped, requester has been notified: Setup experience: Create and manage local user accounts on macOS #27933 (comment)
• Once shipped, dogfooding issue has been filed

Engineering

• Test plan is finalized
• Contributor API changes: No changes
• Feature guide changes: Update guide with edge case scenario where UUID not yet created, rotate password will defer until we get that UUID.
• Database schema migrations: MLAPR: Migration & UUID capture #43885
• This is a premium only feature: Yes

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

QA

Risk assessment

• Risk level: Low

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.

All tests below require a macOS host enrolling from DEP with the managed local account feature enabled (from #43381).

Host details > Show managed account > modal (UUID captured)

• Modal shows username _fleetadmin, masked password, copy + eye (show) buttons, and "Rotate password" secondary button next to primary "Close".
• First view of the password flips status to pending and shows banner: "Password rotates automatically after {time}" where {time} is ~1h5m in the future.
• Re-opening / re-viewing the password within the window shows the same rotation time — timer is not extended.
• Waiting past the rotation time triggers auto-rotation on the next cron tick; next view shows a newly-rotated password and banner resets (status returns to verified before a new view).
• Clicking "Rotate password" rotates immediately, clears the banner, and stops the auto-rotate timer.
• Accessing the password via GET /api/v1/fleet/hosts/:id/managed_local_account/password (API) also triggers the banner on the next modal open — view-via-API has the same effect as view-via-UI.

Host details > Show managed account > modal (UUID not yet captured — deferred)

• On a freshly-enrolled host, the password is still viewable (not blocked).
• Run a DB query to set account_uuid=null in the host_managed_local_account_passwords row for the host. Make sure password is still viewable
• Clicking "Rotate password" returns success (no error toast), modal closes/refreshes cleanly.
• Once the host's next osquery detail cycle ingests _fleetadmin, the pending rotation is fulfilled by the rotation cron within ~5 minutes. Modal then shows the new password.
• The resulting activity for the deferred rotation is credited to the user who clicked Rotate, not Fleet — even though the cron executed it.
• No duplicate activity is recorded for the deferred rotation (user activity at click time, no Fleet activity at cron time).

Host details > Activity

• After manual rotation, activity Rotated managed local account password appears with the triggering user as actor.
• After auto-rotation (waiting past the timer), activity appears with "Fleet" as actor.
• After deferred manual rotation (clicked pre-UUID, fulfilled by cron), exactly one activity appears, with the user as actor.
• host_display_name and host_id render correctly in the activity copy.
• Verify if command fails, activity shows.

Global activity

• Same activity appears in Global activity for manual rotations (user actor) and auto-rotations (Fleet actor).
• Activity type "Rotated managed local account password" appears in the type filter dropdown and filters correctly.
• Verify if command fails, activity shows.

Regression testing

• Enroll a host with this feature enabled via DEP so a managed local account password exists on v4.85. Upgrade to 4.86
• Make sure viewing the password still decrypts it correctly.
• Make sure a host enrolled prior to v4.86 rotates correctly both via timer-based and manual rotation(see notes above about UUID capture - a refetch will have to run after the update before either rotation will actually occur)

** API testing**

• Confirm rotation is triggered when password viewed or accessed via API.

  Additional tests

  • On Fleet Free (no premium license), the rotate endpoint returns an ErrMissingLicense response.
  • Show managed account button is not shown and the endpoint rejects requests for non-macOS hosts (Windows, Linux).
  • On fleet free and fleet premium the host page still works for macOS, windows and Linux hosts, with and without Apple MDM enabled

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.