Using Secure and Bootstrap tokens in deployments
Apple File System (APFS) in macOS 10.13 or later changes how FileVault encryption keys are generated. In previous versions of macOS on CoreStorage volumes, the keys used in the FileVault encryption process were created when a user or organization turned on FileVault on a Mac. In macOS on APFS volumes, encryption keys are generated either during user creation, setting the first user’s password, or during the first login by a user of the Mac. This implementation of the encryption keys, when they’re generated, and how they’re stored are all part of a feature known as Secure Token. Specifically, a secure token is a wrapped version of a key encryption key (KEK) protected by a userʼs password.
When deploying FileVault on APFS, the user can continue to:
Use existing tools and processes, such as a personal recovery key (PRK) that can be stored with a mobile device management (MDM) solution for escrow
Create and use an institutional recovery key (IRK)
Defer enablement of FileVault until a user logs in to or out of the Mac
Starting in macOS 11, setting the initial password for the very first user on the Mac results in that user being granted a secure token. In some workflows, that may not be the desired behavior, as previously, granting the first secure token would have required the user account to log in. To prevent this from happening, add
;DisabledTags;SecureToken to the programmatically created user’s
AuthenticationAuthority attribute prior to setting the user’s password, as shown below:
sudo dscl . append /Users/<user name> AuthenticationAuthority ";DisabledTags;SecureToken"
macOS 10.15 introduced a Bootstrap Token to help with granting a secure token to both mobile accounts and the optional device enrollment-created administrator account (“managed administrator”). In macOS 11, the bootstrap token can grant a secure token to any user logging in to a Mac computer, including local user accounts. Using the bootstrap token feature of macOS 10.15 or later requires:
MDM vendor support
In macOS 10.15.4 or later, a bootstrap token is generated and escrowed to MDM on the first login by any user who is secure token enabled if the MDM solution supports the feature. A bootstrap token can also be generated and escrowed to MDM using the
profiles command-line tool, if needed.
In macOS 11, the bootstrap token may also be used for more than just granting secure token to user accounts. On a Mac computer with Apple silicon, the bootstrap token, if available, can be used to authorize the installation of both kernel extensions and software updates when managed using MDM.
When a user sets up a Mac on their own
When a user sets up a Mac on their own, IT departments don’t perform any provisioning tasks on the actual device. All policies and configurations are provided using an MDM solution or configuration management tools. Setup Assistant is used to create the initial local account, and the user is granted a secure token. If the MDM solution supports the bootstrap token feature and informs the Mac during MDM enrollment, a bootstrap token is generated by the Mac and escrowed to the MDM solution.
If the Mac is enrolled in an MDM solution, the initial account may not be a local administrator account, but rather a local standard user account. If the user is downgraded to a standard user using MDM, the user is automatically granted a secure token. If the user is downgraded, in macOS 10.15.4 or later, a bootstrap token is automatically generated and escrowed to the MDM solution if it supports the feature.
If local user account creation in Setup Assistant is skipped altogether using MDM and a directory service with mobile accounts is used instead, the mobile account user is granted a secure token during login. After the user is secure token-enabled, in macOS 10.15.4 or later, a bootstrap token is automatically generated at login and escrowed to the MDM solution if it supports the feature.
In any of the above scenarios, because the first and primary user is granted a secure token, they can be enabled for FileVault using deferred enablement. Deferred enablement allows the organization to turn on FileVault, but defer its enablement until a user logs into or out of the Mac. Itʼs also possible to customize if the user can skip turning on FileVault (optionally a defined number of times). The end result is the primary user of the Mac—whether a local user of any type or a mobile account—being able to unlock the storage device when encrypted with FileVault.
On Mac computers where a bootstrap token was generated and escrowed to an MDM solution, if another user logs in to the Mac at a future date and time, the bootstrap token is used to automatically grant a secure token, meaning the account is also enabled for FileVault and able to unlock the FileVault volume. To modify whether a user account can unlock the volume, use
fdesetup remove -user.
When a Mac is provisioned by an organization
When a Mac is provisioned by an organization before being given to a user, the IT department sets up the device. The local administrative account created either in the Setup Assistant, or provisioned using MDM, is used to provision or set up the Mac, and is granted the first secure token during login. If the MDM solution supports the bootstrap token feature, a bootstrap token is also generated and escrowed to the MDM solution.
If the Mac is joined to a directory service and configured to create mobile accounts, and if there is no bootstrap token, directory service users are prompted at first login for an existing secure token administratorʼs user name and password to grant their account a secure token. A currently secure token-enabled local administrator’s credentials should be entered. If secure token isnʼt required, the user can click Bypass. In macOS 10.13.5 or later, itʼs possible to suppress the secure token dialog completely if FileVault isn’t going to be used with the mobile accounts. To suppress the secure token dialog, apply a custom settings configuration profile from MDM with the following keys and values:
If the MDM solution supports the bootstrap token feature and one was generated by the Mac and escrowed to the MDM solution, mobile account users won’t see this prompt. Instead, they are automatically granted a secure token during login.
If additional local users are required on the Mac instead of user accounts from a directory service, those local users are automatically granted a secure token when they are created in System Preferences > Users & Groups by a currently secure token-enabled administrator. If creating local users using the command-line, the
sysadminctl command-line tool can be used, and can optionally enable them for secure token. Even if not granted a secure token at time of creation, in macOS 11, a local user logging in to a Mac is granted a secure token during login if a bootstrap token is available from MDM.
In these scenarios, the following users can unlock the FileVault-encrypted volume:
The original local administrator used for provisioning
Any additional directory service users granted secure token during the login process, either interactively using the dialog prompt, or automatically with the bootstrap token
Any new local users
To modify the whether specific accounts can unlock the storage device, the user can use
fdesetup remove -user.
When using one of the above described workflows, secure token is managed by macOS without any additional configuration or scripting being needed; it becomes an implementation detail and not something that needs to be actively managed or manipulated.
Command-line tool usage
Command-line tools are available for managing bootstrap token, FileVault, and secure token. The bootstrap token is usually generated on the Mac and escrowed to the MDM solution during the macOS setup process after the MDM solution tells the Mac that it supports the feature. However, a bootstrap token can also be generated on a Mac that has already been deployed. In macOS 10.15.4 or later, a bootstrap token is generated and escrowed to MDM on the first login by any user who is secure token enabled if the MDM solution supports the feature. This reduces the need to use the profiles command-line tool after device setup to generate and escrow a bootstrap token to the MDM solution.
profiles command-line tool has a number of options to interact with the bootstrap token:
sudo profiles install -type bootstraptoken: This command generates a new bootstrap token and escrows it to the MDM solution. This command requires existing secure token administrator information to initially generate the bootstrap token, the MDM solution must support the feature, and the Mac computer’s serial number must appear in Apple School Manager or Apple Business Manager and enrolled in that specific MDM solution.
sudo profiles remove -type bootstraptoken: Removes the existing bootstrap token on the Mac and the MDM solution.
sudo profiles status -type bootstraptoken: Reports back whether the MDM solution supports the bootstrap token feature, and what the current state of the bootstrap token is on the Mac.
sudo profiles validate -type bootstraptoken: Reports back whether the MDM solution supports the bootstrap token feature, and what the current state of the bootstrap token is on the Mac.
fdesetup command-line tool
MDM configurations or the
fdesetup command-line tool can be used to configure FileVault. In macOS 10.15 or later, using
fdesetup to turn on FileVault by providing the user name and password is deprecated and won’t be recognized in a future release. It continues to function but remains deprecated in macOS 11. Consider using deferred enablement using MDM instead. To learn more about the
fdesetup command-line tool, launch the Terminal app and enter
man fdesetup or
fdesetup help for additional information.
sysadminctl command-line tool
sysadminctl command-line tool can be used to specifically modify secure token status for user accounts on a Mac computer. This should be done with caution and only when necessary. Changing the secure token status of a user using
sysadminctl always requires the user name and password of an existing secure token-enabled administrator, either interactively or through the appropriate flags on the command. Both
sysadminctl and System Preferences prevent the deletion of the last administrator or secure token-enabled user on a Mac. If the creation of additional local users is scripted using
sysadminctl, for those users to be enabled for secure token, current secure token-enabled administrator credentials are required to be supplied either using the interactive option, or directly with the
-adminPassword flags with
sysadminctl. If not granted a secure token at time of creation, in macOS 11, a local user logging in to a Mac computer is granted a secure token during login if a bootstrap token is available from MDM. Use
sysadminctl -h for additional usage instructions.