Bootstrap Token Management on macOS
Introduction
A bootstrap token is an MDM-managed credential that helps macOS extend trust to users and device-management operations without requiring an administrator to hand off credentials interactively. On macOS 10.15.4 and later, a secure-token-enabled user's first login can generate and escrow a bootstrap token when the MDM service supports it.
Secure tokens and bootstrap tokens
A secure token represents a user's cryptographic authority on the Mac and is tied to FileVault unlock eligibility. A bootstrap token is escrowed to the MDM service and can grant secure tokens to eligible users under Apple's supported workflows.
Bootstrap tokens are not limited to mobile-account creation. Depending on the macOS version and hardware, Apple also uses them for Apple silicon management, managed software updates, Erase All Content and Settings, and Platform SSO user workflows.
Why escrow matters
Without an escrowed bootstrap token, administrators can encounter credential prompts or users who are not eligible for expected FileVault and management operations. Escrow gives FileWave MDM a device-specific token it can return when macOS requests it.
The exact user-creation and token behavior depends on the macOS version, enrollment method, account type, and whether an existing user already has a secure token. Verify the device's escrow status instead of inferring success from enrollment alone.
What bootstrap tokens provide
For supported user workflows, macOS can use the escrowed bootstrap token to grant secure-token eligibility without requiring another secure-token-enabled administrator to enter credentials. The rest of this article shows how FileWave handles SetBootstrapToken and GetBootstrapToken requests and how to verify the result.
What Happens Under the Hood?
When FileWave MDM advertises bootstrap-token support during enrollment, macOS can send SetBootstrapToken to escrow a token and GetBootstrapToken when it needs the escrowed token later.
Use the status command in Check Escrow/Server Status below to verify both server support and device escrow.
These two MDM communications are described in the following sections.
SetBootstrapToken request
When macOS generates a bootstrap token on an eligible Automated Device Enrollment (ADE) device, it sends the SetBootstrapToken request to the FileWave MDM server. FileWave encrypts the device's bootstrap token and stores it in the inventory database.
|
|
| Figure 1.1 |
Do not infer escrow from the Setup Assistant path. Account type, enrollment settings, macOS version, and the presence of a secure-token-enabled user all affect when macOS generates and escrows the token. Verify the result with profiles status -type bootstraptoken.
|
|
|
| Figure 1.2 — Captured Setup Assistant configuration (legacy DEP terminology) | Figure 1.3 — Captured standard-user Setup Assistant configuration |
|
|
| Figure 1.4 — Captured Setup Assistant configuration with local user creation skipped |
| Trigger Escrow |
Escrowing of Bootstrap Token to server can be called with: |
GetBootstrapToken request
When macOS needs the escrowed token for an eligible user or management operation on an ADE device, it sends GetBootstrapToken to the MDM server. FileWave returns the stored token for that device. For user workflows, this can allow macOS to grant a secure token without another administrator entering credentials. To inspect the cryptographic users that can unlock the FileVault volume, run:
diskutil apfs listcryptousers /
There you can see the UUID of the mobile account as well as the Bootstrap Token External Key:
Cryptographic users for disk1s5 (9 found)
|
+-- JJJJJJJJ-UUUU-IIII-OOOO-AAAAAAAAAAAA
| Type: Local Open Directory User
|
+-- KKKKKKKK-LLLL-MMMM-NNNN-BBBBBBBBBBBB
| Type: MDM Bootstrap Token External Key
|
+-- GGGGGGGG-WWWW-QQQQ-ZZZZ-CCCCCCCCCCCC
| Type: Local Open Directory User
|
+-- BBBBBBBB-AAAA-MMMM-BBBB-AAAAAAAAAAAA
| Type: iCloud Recovery User
|
+-- DDDDDDDD-0000-EEEE-DDDD-EEEEEEEEEEEE
| Type: iCloud Recovery External Key
|
+-- TTTTTTTT-0000-WWWW-TTTT-WWWWWWWWWWWW
| Type: Personal Recovery User
|
+-- NNNNNNNN-EEEE-SSSS-NNNN-EEEEEEEEEEEE
| Type: Institutional Recovery User
|
+-- JJJJJJJJ-0000-CCCC-JJJJ-CCCCCCCCCCCC
| Type: Institutional Recovery External Key
|
+-- AAAAAAAA-EEEE-FFFF-CCCC-DDDDDDDDDDD
Type: Personal Recovery Key
Compare that list with
sudo fdesetup list
to show the same UUIDs of the accounts that have SecureTokens:
localadmin, JJJJJJJJ-UUUU-IIII-OOOO-AAAAAAAAAAAA
mobileaccount,GGGGGGGG-WWWW-QQQQ-ZZZZ-CCCCCCCCCCCC
Check Escrow/Server Status
To check if Bootstrap Token was escrowed to the server, the same command as above can be used:
sudo profiles status -type bootstraptoken
| Server Supported | Server Does not support |
|
|
| Not Escrowed | Escrowed Done |
If the Bootstrap Token was not escrowed on the server (SetBootstrapToken request was not sent to MDM server or was not handled by MDM server properly), the output will be: |
If the Bootstrap Token is already on the server the output will be:
|
Mobile-account examples
These examples document Catalina-era mobile and network account behavior. On current macOS releases, use them to understand the original credential problem, then verify the supported identity, FileVault, and Platform SSO workflow for your deployed release.
Example 1 - mobile account is created manually by an admin which doesn't have a Secure Token
Problem:
In macOS 10.15+ with FileVault is turned on, a network account login without Secure Token escrowed will be prompted for an admin who does have a secure token.
|
|
| Figure 2.1 |
Solution:
In this Catalina-era mobile-account example, an escrowed bootstrap token allowed macOS to continue without another secure-token-enabled administrator entering credentials. On current macOS releases, verify the user's secure-token status and FileVault unlock eligibility rather than relying on the presence of a Bypass button.
Check a user's secure-token status
Run the following command with the actual short user name:
sudo sysadminctl -secureTokenStatus USERNAME
Do not remove a secure token as a routine troubleshooting step. Changing token ownership can affect FileVault unlock access and must be planned against the device's remaining token-enabled users and recovery path.
Example 2 - mobile account is created automatically when profile Mobility is used
With macOS 10.15 and FileVault turned on, profile Mobility was installed on the device with the option 'Create mobile account when user logs in to network account'.
|
|
| Figure 2.2 |
After a network account login, a mobile account is created automatically (as the "Bypass" button from the dialog "Enter a SecureToken ..." was pressed implicitly). A new mobile account will be shown at startup window after the device reboots.
In comparison: when the same actions are done on macOS 10.14, there is one additional dialog (see figure 2.1) to enter a SecureToken administrator's name and password during the auto-creation of a mobile user. If "Bypass" will be pressed, the new mobile account will not be shown at the startup window after the device reboots and FileVault should be enabled manually for each new mobile account.
Summary
With a supported enrollment and an escrowed bootstrap token, macOS can add eligible users to the secure-token and FileVault workflow without the manual credential handoff required by older deployments. Always verify escrow status and the actual FileVault user list on the device.
No comments to display
No comments to display