Get unlock PIN immediately after locking macOS host

[dherder]

Goal

User story
As a Client Platform Engineer (CPE) who just locked a macOS host,
I want to get the unlock PIN right away
so that I can record the PIN in a ticket I create to track the host and how to unlock it.

Context

• Product designer: @noahtalerman

Changes

Product

• [x] UI changes: No UI changes
• [x] CLI usage changes: No CLI changes
• [ ] REST API changes:

  • 20123

• [x] Permissions changes: No permissions changes
• [ ] Outdated documentation changes: Only updates the REST API docs (see PR above). No other doc changes.
• [x] Changes to paid features or tiers: No changes to paid features. Lock is still Fleet Premium only.

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

• Requires load testing: No
• Risk level: Low

Manual testing steps

Original lock/unlock flow

1. Lock macOS via GUI. The state should go to 'lock pending' and then 'locked'.
2. Get the PIN by clicking Unlock in GUI. The device should still be 'locked' in GUI.
3. Unlock device with the PIN. Device should be unlocked in the GUI.

New lock/unlock flow

1. Lock macOS via updated API endpoint. The state should go to 'lock pending' and then 'locked' in GUI.
2. Unlock device with the PIN. Device should be unlocked in the GUI.

Testing notes

Confirmation

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

[noahtalerman]

the unlock PIN is only available via API and UI when the device actually checks in and receives the lock device command (moved from Pending to Locked)

Hey @dherder I think one can get the unlock PIN right after they issue the lock command using the Unlock host API endpoint here.

My understanding is that endpoint returns the PIN for macOS hosts even before the host receives the lock command.

@rachaelshaw let me know if I'm wrong about the above.

[rachaelshaw]

@noahtalerman the PIN exists as soon as the lock command is sent, but the API may still throw an error. Looks like we didn't specify whether the error message applies to all platforms: https://www.figma.com/design/FCmmIh1y1DTzlRF5JsH3wh/%239949-%26-%239951-Remote-lock-and-remote-wipe-for-macOS%2C-Windows%2C-and-Linux?node-id=471-5125&t=lPOsipN6ncTb4gqu-1

[dherder]

@noahtalerman when I run a query to the unlock endpoint with a host that has a pending lock, I get an empty response, not an error. If this is the case, based on what you've noted above, this appears to be a bug. Can you confirm please?

[noahtalerman]

Hey @dherder can you please file a bug for it but add it to the drafting board (:product) instead of the release board?

I think we want to bring this to design review to dig into the expected behavior.

cc @rachaelshaw

[dherder]

@noahtalerman I updated the title and added steps to repro. Are the labels correct?

[noahtalerman]

@dherder looks good! Thanks.

@rachaelshaw passed this one to you. I think let's discuss during our next design review.

[zayhanlon]

hey @noahtalerman is there any feedback on this yet?

[JoStableford]

Related to a Slack conversation

[noahtalerman]

it seems that the unlock PIN is only available via API and UI when the device actually checks in and receives the lock device command

Hey @zayhanlon it looks like we designed it to work this way but we got it wrong!

Because the feature was built as intended, I removed the bug label and added story. I pulled this story into the current design sprint which means we're targeting shipping the improvement in the next engineering sprint (target date 2024-07-15)

We can accelerate this as-needed if the target ship date will slow down the customer's migration. Let me know.

[zayhanlon]

@noahtalerman i hate to use the 'escalate' button too frequently, but that won't work for migration timelines here. let me know if there's anything i can help with in terms of re-prioritizing customer asks in the current sprint but would be great to push this through faster

@dherder @alexmitchelliii FYI

[zayhanlon]

The team will be building out their ITIL workflows that will involve capturing the lock code when an employee is offboarded. With the way the feature is designed today, they can't do that and will be forced down a manual road of checking when the device comes online to capture the code manually. This is a really bad experience, especially for crucial actions like an employee offboarding where you want things to go smoothly.

[noahtalerman]

Hey @dherder heads up, I updated this issue to the user story format and moved your original issue description below for safekeeping.

---

Problem

customer-rosner wants to record the lock device PIN as soon as a lock device command is issued. The problem is, it seems that the unlock PIN is only available via API and UI when the device actually checks in and receives the lock device command (moved from Pending to Locked). Today, there does not seem to be a way to get that PIN at the time of the Lock device command is issued.

More context: recording the unlock PIN in a ticketing system is the background on why the PIN needs to be captured as soon as the command is executed. If the device is offline, they would still like to record the PIN at that time of issuance.

The only way I could find to get the command results payload is via this deprecated api, we should add this to the public api.

How to repro:

1. Lock a macOS device when the device is not online
2. make a GET request to the unlock endpoint (https://fleetdm.com/docs/rest-api/rest-api#unlock-host)
3. Note that an empty response is returned

Expected behaviour

When making the GET request, the unlock PIN should be returned

[noahtalerman]

Hey @dherder, instead of returning the PIN via the POST /hosts/:id/unlock API endpoint (as discussed during today's product office hours), the updated plan it to return the PIN in the response for the POST /hosts/:id/lock API endpoint.

Check out the API wireframes here: https://github.com/fleetdm/fleet/pull/19671/files

Why? This is the quickest iterative change we can make.

Do you know if this works for the requestors ticket creation workflow? Please feel free to tag them here in GitHub if they're cool with that :)

[dherder]

@noahtalerman yes, this approach works for the customer.

[noahtalerman]

Hey @lukeheath, I think we want to pull it into the current sprint (target date 2024-06-24). I added the P2 label. See @zayhanlon's comment re next sprint being too slow here.

The story is settled but hasn't been estimated. I don't think it should be a huge lift (could be wrong). It's a change to one API endpoint (see issue description).

I think either the MDM or Endpoint Ops team is equipped to take it. Both teams have contributors who are familiar with the lock feature. Up to you and the EMs.

[sharon-fdm]

Est (just BE changes): BE 2 (bold est)

[lukeheath]

@noahtalerman @zayhanlon Since this blocks the existing migration timeline it justifies an escalation to P2. I've moved this to the release board and assigned @sharon-fdm.

@noahtalerman This seems like an MDM task but you re-labeled to EO. I'm assuming EO is assisting MDM on this, so I've added the appropriate label. Let me know if I'm mistaken.

@sharon-fdm Please make sure this merges before freeze next week. We will need to be more stringent about merging features after freeze as part of our effort to get release on the target release dates.

[getvictor]

@zayhanlon @noahtalerman The fix is on main. We can put this into the upcoming 4.51.2 patch if needed.

[zayhanlon]

Yes please! @getvictor

[georgekarrv]

On main the Lock action is no longer present in the UI.

[georgekarrv]

[13:38:48 gkarr@redbeast fleet] (main)$ ./build/fleetctl mdm lock --host A6D72F40-8BF3-51C0-9DD2-F7BDD1477EB2
Warning: Version mismatch.
Client Version:   fleet-v4.51.0-128-gb01389ad3-dirty
Server Version:  0.0.0-SNAPSHOT-b01389a

The host will lock when it comes online.

Copy and run this command to see lock status:

fleetctl get host A6D72F40-8BF3-51C0-9DD2-F7BDD1477EB2

When you're ready to unlock the host, copy and run this command:

fleetctl mdm unlock --host=A6D72F40-8BF3-51C0-9DD2-F7BDD1477EB2

No unlock pin for fleetctl

[georgekarrv]

[13:58:32 gkarr@redbeast fleet] (main)$ ./build/fleetctl api -X POST /api/v1/fleet/hosts/2/lock
Warning: Version mismatch.
Client Version:   fleet-v4.51.0-128-gb01389ad3-dirty
Server Version:  0.0.0-SNAPSHOT-b01389a
{
  "unlock_pin": "373403"
}

Raw api on an online host works as expected but there is currently no activity that I viewed the pin

[13:58:45 gkarr@redbeast fleet] (main)$ ./build/fleetctl api -X POST /api/v1/fleet/hosts/2/lock
Warning: Version mismatch.
Client Version:   fleet-v4.51.0-128-gb01389ad3-dirty
Server Version:  0.0.0-SNAPSHOT-b01389a
{
  "unlock_pin": "128604"
}

Raw api on an offline host works as expected but there is currently no activity that I viewed the pin.

So the main break that needs to be addressed is that this host w/ mdm On cannot use the mdm features from the UI anymore.

[georgekarrv]

And address the missing activity that the user who locked the device viewed the pin

[lucasmrod]

I tested Fleet with the changes as of now (commit e2ab9a2fe8c7f71598835ef90c851f0f13e09ecd)

Tests performed: A) Locked+unlocked a macOS device via the UI successfully. B) Locked+unloacked a macOS device using the API with view_pin=true successfully.

You can see the activity for the first lock via the UI has view_pin: false and the second activity for the second lock via the API has view_pin: true.

C) Locked+unlocked a Windows 10 device through the UI successfully. D) Locked+unlocked a Windows 10 device through the API sucessfully.

[marko-lisica]

@noahtalerman TODO: when you get the chance could you add new PR for the API changes and merge it.

[rachaelshaw]

✅ Docs merged

[fleet-release]

Unlock PIN at hand, Swiftly tracks the host through clouds, Fleet ensures safe land.