Ending macOS Password Lockout Tickets With Bootstrap Token Audits

#The Old Way vs the New Way

The old way of handling a locked-out Mac is painfully familiar to every L1 desk. A user calls in convinced they have forgotten their password, but what they have actually lost is the FileVault Personal Recovery Key they were told to write down eighteen months ago and never did. The technician talks them through the recovery key prompt, the key does not work, and the call escalates. If nobody in the business has a valid escrow copy of that key either, the only remaining option is a remote wipe, a full re-provision, and a re-image ticket that eats an entire morning and pulls in a second tier of support. None of that effort fixes anything. It just resets the clock until the next person forgets their password.

The new way removes the human loop before the lockout ever happens. Since macOS Ventura, the login and FileVault unlock screen has included a native Reset Password option that talks directly to the enrolled MDM server using the device’s escrowed bootstrap token. No recovery key, no Apple ID, no technician typing anything into Terminal, and no ticket. The entire job for support engineering shifts from reactively resetting passwords to continuously auditing and remediating bootstrap token escrow across the fleet, so the self-service reset button actually works the one time in twelve months a user needs it.

#Why Bootstrap Token Escrow Is the Real Fix

A bootstrap token is a cryptographic credential that macOS generates locally and escrows to the MDM server the first time a Secure Token-enabled administrator authenticates on a supervised Mac. Apple’s device management documentation describes three things it is used for: authorising MDM to create new Secure Token administrator accounts without a human present, approving certain system extension and software update operations silently, and, since Ventura, authorising a password reset request initiated from the lock screen itself. The mechanism only works if the token was successfully escrowed in the first place, and that escrow step is fragile in ways that rarely surface until the exact moment someone is locked out.

The most common escrow failure in enterprise fleets is a device that enrolled through Automated Device Enrollment before any Secure Token-enabled account ever logged in locally, or a Mac where the first login was a mobile or network account rather than a local administrator. In both cases, profiles status will happily report that the device is enrolled and supervised while the bootstrap token itself is empty. Nobody notices until the FileVault screen offers a Reset Password button that quietly fails, and the ticket lands anyway, except now the technician has to explain why the fix that was supposed to be automatic did not fire.

The correction is to stop treating bootstrap token escrow as a one-time enrollment detail and start treating it as a fleet health metric, audited daily and remediated automatically wherever it is missing, well before anyone tries to use it.

#Prerequisites and Permissions

• Fleet baseline: macOS Ventura 13 or later on target devices, supervised through Automated Device Enrollment or a Jamf Pro-managed enrollment that supports bootstrap token escrow.
• MDM platform: Jamf Pro 10.x or later with the Bootstrap Token payload enabled under Global Management Settings. Microsoft Intune administrators should confirm bootstrap token escrow support against their current enrollment profile configuration before adapting this workflow.
• Local execution context: the audit script must run as root, so it is deployed as a LaunchDaemon, not a LaunchAgent, and pushed through a Jamf Pro policy or equivalent configuration profile payload.
• Jamf Pro API role: a dedicated service account named something like svc-bootstrap-audit, scoped to Read Smart Computer Groups and Read Computers only. It must never hold Send Remote Commands or Update Computers privileges, because this workflow is read-and-report, not destructive.
• Webhook endpoint: a Slack or Microsoft Teams incoming webhook URL for non-compliance alerts, stored as a Jamf Pro script parameter or an Intune-managed configuration value, never hard-coded in a script committed to source control.
• Test scope: a pilot Smart Group of no more than twenty devices across at least two hardware models and both Apple Silicon and Intel where still present, run for one full week before fleet-wide deployment.

#Implementation Steps

1. Confirm supervision and OS baseline. Action: run profiles show -type enrollment on a sample of five devices to confirm ADE supervision and enrollment type. Expected result: output shows “MDM enrollment: Yes (Supervised)”. Evidence: capture the raw output for each sampled serial number and store it against the change ticket.
2. Check bootstrap token status locally. Action: run the command below on the same sample. Expected result: a clear YES or NO for escrow status. Evidence: screenshot or saved terminal log per device.
   Terminal

   sudo profiles status -type bootstraptoken

   Expected output example:

   Terminal

   1Bootstrap Token supported on server: YES
   2Bootstrap Token escrowed to server: YES

3. Deploy the audit script as a LaunchDaemon. Action: push the script and plist below through a Jamf Pro policy scoped to the pilot Smart Group. Expected result: the LaunchDaemon loads and runs daily at 08:00 local time. Evidence: sudo launchctl list shows com.kby.bootstraptoken.check with a zero last exit status.
   Terminal

   1sudo mkdir -p /usr/local/kby
   2sudo tee /usr/local/kby/check-bootstrap-token.sh >/dev/null <<'EOF'
   3#!/bin/zsh
   4STATUS=$(/usr/bin/profiles status -type bootstraptoken 2>&1)
   5RESULT="UNKNOWN"
   6if echo "$STATUS" | /usr/bin/grep -q "escrowed to server: YES"; then
   7  RESULT="ESCROWED"
   8elif echo "$STATUS" | /usr/bin/grep -q "escrowed to server: NO"; then
   9  RESULT="MISSING"
   10fi
   11echo "<result>${RESULT}</result>"
   12HOSTNAME=$(/usr/sbin/scutil --get ComputerName)
   13SERIAL=$(/usr/sbin/ioreg -l | /usr/bin/grep IOPlatformSerialNumber | /usr/bin/awk -F'"' '{print $4}')
   14if [ "$RESULT" = "MISSING" ]; then
   15  WEBHOOK_URL="https://hooks.slack.com/services/REPLACE/WITH/WEBHOOK"
   16  PAYLOAD=$(cat <<JSON
   17{"text": "Bootstrap token missing on ${HOSTNAME}, serial ${SERIAL}"}
   18JSON
   19)
   20  /usr/bin/curl -sS -X POST -H "Content-Type: application/json" -d "$PAYLOAD" "$WEBHOOK_URL"
   21fi
   22exit 0
   23EOF
   24sudo chmod 755 /usr/local/kby/check-bootstrap-token.sh

4. Register the LaunchDaemon. Action: write and load the plist that runs the script daily. Expected result: launchctl print system/com.kby.bootstraptoken.check shows state “running” or “waiting”. Evidence: exported plist content attached to the deployment record.
   Terminal

   1sudo tee /Library/LaunchDaemons/com.kby.bootstraptoken.check.plist >/dev/null <<'EOF'
   2<?xml version="1.0" encoding="UTF-8"?>
   3<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   4<plist version="1.0">
   5<dict>
   6  <key>Label</key>
   7  <string>com.kby.bootstraptoken.check</string>
   8  <key>ProgramArguments</key>
   9  <array>
   10    <string>/usr/local/kby/check-bootstrap-token.sh</string>
   11  </array>
   12  <key>StartCalendarInterval</key>
   13  <dict>
   14    <key>Hour</key>
   15    <integer>8</integer>
   16    <key>Minute</key>
   17    <integer>0</integer>
   18  </dict>
   19  <key>RunAtLoad</key>
   20  <true/>
   21</dict>
   22</plist>
   23EOF
   24sudo chown root:wheel /Library/LaunchDaemons/com.kby.bootstraptoken.check.plist
   25sudo chmod 644 /Library/LaunchDaemons/com.kby.bootstraptoken.check.plist
   26sudo launchctl bootstrap system /Library/LaunchDaemons/com.kby.bootstraptoken.check.plist

5. Wrap the script as a Jamf Pro Extension Attribute. Action: create a script-based EA named “Bootstrap Token Status” using the same logic, run at inventory update. Expected result: the EA populates ESCROWED or MISSING against every managed record. Evidence: Jamf Pro inventory record showing the EA value with a timestamp.
6. Build the non-compliance Smart Group. Action: create a Smart Group named Bootstrap-Token-Not-Escrowed with the criterion Bootstrap Token Status equals MISSING. Expected result: the group populates automatically on the next inventory cycle. Evidence: exported member list with serial numbers and last check-in dates.
7. Automate the first remediation pass. Action: scope a policy to the non-compliant Smart Group that forces an immediate MDM check-in, which re-attempts escrow if the underlying cause was a stale enrollment record rather than a genuinely missing Secure Token. Expected result: devices move out of the Smart Group within one inventory cycle after remediation succeeds. Evidence: before-and-after Smart Group counts.
   Terminal

   sudo profiles renew -type enrollment

   Expected output example:

   Terminal

   Enrollment profile renewal requested.

8. Query fleet compliance through the Jamf Pro API for reporting. Action: authenticate with the read-only service account and pull the Smart Group membership. Expected result: a JSON or XML response listing current non-compliant devices. Evidence: saved API response attached to the weekly compliance report.
   Terminal

   1AUTH_RESPONSE=$(curl -s -X POST "https://yourorg.jamfcloud.com/api/v1/auth/token" -u "svc-bootstrap-audit:REPLACE_WITH_SECRET")
   2TOKEN=$(echo "$AUTH_RESPONSE" | /usr/bin/plutil -extract token raw -o - -)
   3curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" "https://yourorg.jamfcloud.com/JSSResource/computergroups/name/Bootstrap-Token-Not-Escrowed"

   Expected response fragment:

   JSON payload

   1{
   2  "computer_group": {
   3    "id": 214,
   4    "name": "Bootstrap-Token-Not-Escrowed",
   5    "is_smart": true,
   6    "computers": [
   7      { "id": 118, "name": "MBP-J-DOE", "serial_number": "C02XXXXXXX" }
   8    ]
   9  }
   10}

#Verification and Expected Evidence

Verification has to happen on a real device, not just in API output, because the whole point is that the lock-screen button works when a real user needs it. On a pilot Mac with escrow confirmed as YES, sign out, click the small question mark or Reset Password prompt at the login window, and confirm the flow completes without requesting a personal recovery key or Apple ID. Capture a screen recording or timestamped screenshot of the successful reset as evidence, plus the Jamf Pro management history entry showing a completed check-in around the same timestamp.

At the fleet level, expected evidence is a Smart Group count trending toward zero over the first two weeks of rollout, an Extension Attribute history graph in Jamf Pro showing the proportion of ESCROWED devices climbing past 98 percent, and a weekly exported API report attached to the change record for audit purposes.

#Rollback

This workflow is intentionally low blast radius because it only audits and forces a routine check-in; it never resets a password or erases a device on its own. Rollback is correspondingly simple. Unload the LaunchDaemon with sudo launchctl bootoutsystem/com.kby.bootstraptoken.check, remove the plist and script from disk, delete the Jamf Pro policy scoping the remediation step, and disable or delete the Extension Attribute if it is generating noise. No FileVault state, account, or encryption key is touched at any point, so there is no data-loss rollback path to manage.

#Failure and Escalation Conditions

• If more than five percent of a Smart Group population remains in MISSING status after two consecutive remediation cycles (roughly 48 hours), escalate to L3 for individual device investigation, since a forced check-in that repeatedly fails to re-escrow usually means the device never had a Secure Token-enabled local account at all.
• If the webhook alert fires more than ten times in a single day, treat it as a signal that a fleet-wide enrollment or configuration profile change has broken escrow generally, not an isolated device issue, and pause further rollout until the root cause is identified.
• If the Jamf Pro API authentication call returns a 401 or 403, rotate the service account credential immediately and confirm the role assignment has not been broadened beyond the read-only scope defined above.
• Wake a human technician immediately if a user reports that the Reset Password button at the login screen is present but returns an error after entering a new password twice, since this indicates a token that is escrowed but corrupted, which the audit script cannot distinguish from a healthy token and requires a manual bootstrap token reissue.

#Measuring Ticket Deflection

Baseline the current volume of password-reset and FileVault-lockout tickets for sixty days before rollout, tagged by category in the service desk tool. After rollout, track three numbers weekly: the Smart Group non-compliance count, the percentage of ESCROWED devices reported by the Extension Attribute, and the raw count of password-reset tickets that required technician intervention versus those resolved entirely by the user at the login screen with no ticket logged at all. A fleet that moves from roughly 70 percent escrow coverage to above 98 percent typically sees lockout-related tickets requiring technician time drop by more than half within the first month, because the remaining failures are genuine edge cases rather than routine escrow gaps.