The secure token and bootstrap tokens are two key components for efficiently managing devices via MDM. Issues with these two tokens can lead to difficult scenarios, such as users not being able to log in, and in some cases, locking out the device to a point where an erase is required. Generally speaking, it is crucial that applicable users have a secure token and that devices have the bootstrap token escrowed to Addigy. In this article, we will be covering what they are, how they work, and some troubleshooting steps for certain scenarios.
Table of Contents
- What is a Secure Token
- What is the Bootstrap Token
- Verifying Token Statuses
- FAQs and Remediating Common Issues
What is a Secure Token
Simply, the secure token is a special pass for user accounts that allows them to perform certain actions. For example:
- Unlocking FileVault at startup
- Enabling FileVault (either locally via System Settings or Deferred Enablement through an MDM Profile)
- Performing System Updates
The first user account created on macOS will automatically receive a secure token. Once an account has a secure token, it can also grant secure tokens to other accounts through various methods. However, accounts created through command-line tools or Active Directory mobile accounts do not automatically receive secure tokens and require manual intervention. This is where the bootstrap token comes in.
What is the Bootstrap Token
The bootstrap token allows the MDM provider more access to devices. With the bootstrap token escrowed, Addigy can:
- Automatically grant new users a secure token after they log in
- Manage System Updates
- Silently erase devices using EACS
- Send MDM Settings commands
This bootstrap token will automatically be escrowed to the MDM provider once the device has been enrolled in MDM. In the case of manual MDM enrollment, if an admin user without a secure token enrolls in MDM, the Bootstrap Token will not get escrowed.
Verifying Token Statuses
Secure token
1 - GoLive > Users
Addigy will automatically detect the status of each user's Secure Token. If a user has a secure token, it will be noted in the UI like so:
2 - Running terminal commands
Various commands can obtain this information, but the primary command is as follows:
sysadminctl -secureTokenStatus <usernamehere>If a device is using FileVault, this command will list all users who can unlock FileVault:
sudo fdesetup listBootstrap token
The only command to view the status of the bootstrap token is the following:
sudo profiles status -type bootstraptokenIf the token is properly escrowed, both values will report "YES", like so:
If the token is not escrowed, the second value will say "NO", like so:
If you'd like to make a custom fact to view this information at a glance in Addigy, you can use this script:
check_bootstrap=$(profiles status -type bootstraptoken)
if [[ $check_bootstrap == *"escrowed to server: YES"* ]]; then
echo true
else
echo false
fiMake sure to configure the "Return Type" as a boolean and set it to Bash, like so:
FAQs and Remediating Common Issues
Bootstrap token is not escrowed
If a device has not escrowed the bootstrap token, you will need to use the following command to escrow it:
sudo profiles install -type bootstraptokenThis command requires you to input the credentials of an admin user with a secure token user.
If you have access to a local admin user with a secure token, you can easily use this command via LiveTerminal. To do this:
- Initiate a LiveTerminal session
- Run the command to escrow the bootstrap token
- You will be prompted to enter the secure token admin username and password
- After entering the credentials, the bootstrap token will escrow
User does not have a secure token
If a user does not have a secure token, the first thing to check is whether the bootstrap token is escrowed.
If it is escrowed, all the user needs to do is log in, and they will receive a secure token via the bootstrap token.
If it is not escrowed, you will need to evaluate whether there is an admin user with a secure token and follow either section that suits the situation.
1 - Admin exists with secure token
If the device has an admin user with a secure token, follow the steps in this section to escrow the bootstrap token. Then, have the user log in, and they will obtain a secure token. If you do not know the credentials of the admin user, do not reset the password via Addigy. Resetting the password will break the secure token and worsen the situation. Follow the steps directly below in option #2 if that is the case.
2 - No secure token admin / secure token admin is not accessible
In this instance, the only way to obtain a secure token without the bootstrap token escrowed is to reset the passwords via recovery. This guide covers the steps needed to accomplish that.
Fixing Broken Keychains (Secure Tokens) using Recovery Mode
Note: If you have FileVault enabled, you will need to use the recovery key to access recovery and reset user passwords.
User cannot log in via FileVault
If an end-user reports that they cannot log in, it's important to first confirm whether they cannot log in at the FileVault login window or the default macOS login window, as they are fundamentally different. A key indicator of the device being at the FileVault login window is that the device does not communicate over the internet and thus doesn't show online in Addigy.
If a user is unable to log in via FileVault, that means they have either entered the password incorrectly or the secure token has been broken. When a secure token breaks, FileVault expects the password that was tied to that secure token. Let's say, for example, User A has the password 'Lilies1', but it is reset via GoLive > Users and is now set to 'Roses2'. If the Mac is rebooted before the user performs a login and regains a secure token via the bootstrap token, FileVault will expect 'Lilies1' and not 'Roses2'.
It is crucial to ensure users log in via the regular macOS login window if their password is ever reset. This process will make sure they regain the secure token, so long as the bootstrap token is escrowed.
If the user does not remember their former password, consider if there is another secure token user account on the device. If there is another account, see if someone who knows the password and has physical access to the device can log in as that user. If the owner of the Mac is remote, if you are comfortable doing so, you can share the password with the user and change it later. If neither of these is an option, you will need to follow the most applicable steps covered in this guide: Fixing Broken Keychains (Secure Tokens) using Recovery Mode
Note: Because FileVault is enabled, you will need to use the recovery key to access recovery and reset user passwords. If the FileVault recovery key is not known, an erase might be needed to regain access to the Mac. If you are ever not sure of what the best path forward is, please do not hesitate to reach out to our support team for assistance.
Resetting a password without breaking the secure token
If there is a secure token admin user you know the password for, you can reset the password while maintaining the secure token locally via System Settings > Users & Groups, or by using the sysadminctl command:
sysadminctl -adminUser adminuser -adminPassword adminpasswd -resetPasswordFor usertoreset -newPassword newpasswdBe sure to alter these variables:
- adminuser - The name of the admin user with a secure token
- adminpsswd - The password of the secure token admin
- usertoreset - The target user you are resetting the password for
- newpasswd - The new password of the target user
If you have a secure token admin that you need to reset the password for, but you want to maintain the secure token, you will need to rely on the bootstrap token to grant a secure token at login. Be sure to verify the bootstrap token is escrowed prior to doing this. If the bootstrap token is not escrowed and there are no other secure token admins, please follow this section:
No secure token admin users and the bootstrap token is not escrowed
Resetting the password of the only secure token user
Resetting the password of any user via Addigy (e.g., GoLive > Users) will break the secure token. If you only have one user with a secure token, admin or not, so long as the bootstrap token is escrowed, the user will automatically obtain a secure token the next time they log in.
If you are using FileVault, it is pivotal that the secure token is re-obtained before a reboot is performed. If not, as highlighted in this section, the user will need to enter their previous password.
No secure token admin users and the bootstrap token is not escrowed
1 - Standard user exists with a secure token
If the credentials are known for a standard user on the Mac with a secure token, simply elevate their privileges to admin using our TempAdmin feature. Then, have the user escrow the bootstrap token using this command:
sudo profiles install -type bootstraptokenYou will be prompted to enter an admin username and password, which you will want to use the credentials of the elevated user. Once the bootstrap token has been escrowed, log in as the user(s) without a secure token, and they will obtain this via the now escrowed bootstrap token.
2 - No accessible secure token user
If no secure token user can be leveraged to escrow the bootstrap token, you will need to reset all passwords via recovery. We have a guide on how to do this here: Fixing Broken Keychains (Secure Tokens) using Recovery Mode