About macOS Catalina Bootstrap Token

Catalina introduces a new method of SecureToken enablement called Bootstrap Token. This is a new MDM-based management feature to automatically provide a SecureToken on all mobile account logins.  This does not affect how local accounts get SecureTokens.

Catalina can give the first mobile account to log in a SecureToken if no other accounts have a SecureToken yet (as of 19a573a), but the benefit of Bootstrap Token comes when multiple users log into an encrypted machine. All mobile accounts that log in automatically get a SecureToken without having to hand one off manually.

There are some specific requirements for Bootstrap Token eligibility:

1. An MDM that supports Bootstrap Token.*
2. The MDM has to be associated with Apple Business Manager (ABM) or Apple School Manager (ASM).
3. The client machine must be assigned in ABM or ASM to that MDM. Merely being enrolled in the MDM manually is not enough.
4. The client machine must be enrolled in ABM or ASM, either from Setup Assistant or “nagging” later.
5. Since the Bootstrap Token is used for mobile accounts, the client must be bound to a directory service like Active Directory.

*I worked with SimpleMDM to incorporate Bootstrap Token support in their product so I know they have it.  Talk to your MDM vendor for more details on their support of Bootstrap Tokens.

Bootstrap Token is not a payload or configuration that gets delivered by the MDM to a client computer.  Instead, it is a set of commands that is sent from the client that the MDM needs to know how to process.  Apple’s developer documentation on the MDM spec provides details for Bootstrap Token.

EXPLORING THE ESCROW PROCESS:

If the client is enrolled in MDM and associated to the MDM in ABM or ASM but Bootstrap Token hasn’t been escrowed yet, running
profiles status -type bootstraptoken
will result in:

profiles: Bootstrap Token supported on server: YES
profiles: Bootstrap Token escrowed to server: NO

The first line being the most important.  A YES means that the client is eligible for Bootstrap Token escrow since it is assigned to the MDM in ABM.  If the result is NO then the client isn’t eligible at all and you need to look into what MDM the client is enrolled in and if the client and MDM are associated in ABM.

With a SecureToken enabled admin issue
profiles install -type bootstraptoken.
This process is interactive and requires the username and password to be typed in.

Enter the admin user name:localadmin
Enter the password for user 'localadmin':
profiles: Create Bootstrap Token created
profiles: Bootstrap Token created
profiles: Bootstrap Token escrowing to server...
profiles: Bootstrap Token escrowed

If all goes well, Bootstrap Token is escrowed. To verify, on the client run
sudo profiles status -type bootstraptoken

profiles: Bootstrap Token supported on server: YES
profiles: Bootstrap Token escrowed to server: YES

At this point, if the client is bound to a directory server, when a mobile account logs in a SecureToken will be enabled on the account.

After logging in, list which accounts can unlock the FileVaulted disk with 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 (4 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
|
+-- AAAAAAAA-EEEE-FFFF-CCCC-DDDDDDDDDDDD
Type: Personal Recovery User

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

If FileVault is already encrypted, the new mobile account(s) will be added to the preboot unlock user list automatically. No need to update preboot like past OSes.

HOW CAN THIS BE AUTOMATED TO BE SCALABLE?

For ABM/ASM provisioning, if you don’t suppress the creation of the local admin account in Setup Assistant you’re set. After creating the admin account it automatically logs in and uses the credentials provided at the time of the account creation to escrow the Bootstrap Token. Not all environments allow users, or even techs, to create the first account in Setup Assistant, so what else?

My desired setup – I want a way to have MDM create the local admin account so it is consistent, have the MDM install munki and configure it to bootstrap itself, and by the time munki is done bootstrapping I want the Bootstrap Token to be escrowed automatically so I can hand off the machine to a user to log in without any extra action. Seems pretty reasonable in any environment that has many locations with many techs, but consistent results are expected.

First, there needs to be an admin account with a SecureToken enabled without having to lay hands on the computer.  It turns out that the first time the local admin account authenticates in any way it will have a SecureToken enabled on the account.  The easiest way I’ve found is using dscl‘s -authonly verb to only authenticate the account without actually logging into anything.  That verb does what it says, it just verifies the account credentials, but that’s enough to give it a SecureToken.

Once the SecureToken enabled admin is available, then the command
profiles install -type bootstraptoken
 needs to be issued. The next hurdle in this process is that this command is interactive.  To automate this, a yucky expect script needs to be used to look for prompts and pass the username and password of the account accordingly.

My automated process:

1. Provision the machine via ABM/MDM in Setup Assistant – e.g. it is configured in ABM to enroll in the MDM.
2. MDM enrolls.
3. MDM creates the local admin account and suppresses allowing the user to create any accounts.
4. Munki is installed and configured by an MDM delivered InstallEnterpriseApplication pkg.
5. The first pass of Munki runs a script to authenticate the local admin account to issue a SecureToken and then generates and escrows the Bootstrap Token.
   1. The script authenticates local admin with
      /usr/bin/dscl /Local/Default -authonly localadmin password
   2. I’m not concerned so much about password in the script here as the remaining Munki bootstrap changes that password minutes later
   3. Now with the local admin that has a SecureToken, the script issues
      profiles install -type bootstraptoken
   4. When Munki is finished bootstrapping, any user that logs in against the directory server will have a SecureToken added to the account automatically.

To break this down, Steps 1-3 are standard form for MDM enrollment at Setup Assistant.

Step 4 has the MDM install Munki and configures it to bootstrap.

Step 5 runs the following script.  This script shows how it authenticates the local admin account and includes a yucky expect script to pass the credentials to the interactive-only profiles routine to install the Bootstrap Token:

#!/bin/bash
version=$(sw_vers -productVersion | awk -F. '{print $2}')

if [[ $version -ge 15 ]]
then

# The admin account needs to authenticate to validate its password to enable SecureToken on the account
# Using dscl and -authonly is the least intrusive way to do that.
/usr/bin/dscl /Local/Default -authonly localadmin password

# Kick off the bootstrap token escrow install. The UX is interactive.
# Use expect to supply username and password when prompted.
/usr/bin/expect << BOOTSTRAP

log_file /Users/Shared/expect.log
spawn profiles install -type bootstraptoken
sleep 1
expect "Enter the admin user name:"
sleep 1
send "localadmin\n"
sleep 1
expect "Enter the password for user"
sleep 1
send "password\n"
sleep 1
expect "profiles"
sleep 1
interact
BOOTSTRAP

fi

After this script runs the client has the Bootstrap Token escrowed and yet no one has logged into the computer at all! Success!

Any mobile account that logs in will get a SecureToken.  If FileVault is enrolled via the MDM and in a deferred state then, upon login, the mobile account will be prompted to allow FileVault to encrypt.

TO SUMMARIZE:

• Client must be assigned in ABM to the MDM that supports Bootstrap Token
• If the local admin account is created during Setup Assistant, Bootstrap Token escrows automatically
• If the local admin account is suppressed in Setup Assistant, a SecureToken admin has to run the profiles command to install and escrow.
• If the client machine is enrolled in the supporting MDM but not enrolled in ABM or ASM, assign the client in ABM or ASM to the MDM, enroll into ABM with profiles renew -type enrollment, then run profiles install -type bootstraptoken from a SecureToken enabled admin to escrow.

Advertisement

Clean up shell scripts in BBEdit

Continuing on the topic of using Text Filters in BBEdit as discussed in Clean Up XML Formatting in BBEdit, this hint shows you how to clean up shell scripts.

First download bashbeautify.py from the linked github project.

Create a simple bash script that calls the bashbeautify.py file. The following script uses the --tab-str option to set the default tab character from the script’s default of two spaces to the actual tab character. The --tab-size option sets how many --tab-strs per tab.  The trailing - says to act on stdin which is what the open BBEdit file is. Save the Text Filter script to ​~/Library/Application Support/BBEdit/Text Filters/bashbeautify.sh to make it available to BBEdit

bashbeautify.sh

#!/bin/bash
python ~/Applications/bin/bashbeautify.py --tab-str ' ' --tab-size 1 -

Now open a poorly formatted shell script. You may want to remove all indentations first to have a baseline of no indents. You can accomplish this by selecting all (Command-a) and using Command-[ until all text has shifted left.  Then use the menu Text > Apply Text Filter > bashbeautify.

Example: This hard to read script

turns into this

Clean Up XML Formatting in BBEdit

If you work with XML or .plist files you’ve most likely run into a file that is proper XML but is not human readable due to its formatting.  That usually means running it thru an xml format cleanup process to make it human readable. If you work with those files in BBEdit like I do, there is a feature called Text Filters that allows scripts to be run on the file you’re working on.

Create a simple bash script and save it to ​~/Library/Application Support/BBEdit/Text Filters/plist_format.sh:

#!/bin/bash
plutil -convert xml1 -o - -- -

Now if you have a file open that has no line breaks or indentation like this:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0">...

Access the script in BBEdit in Text->Apply Text Filter->plist_format and it will format the output in-app.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>distribution_style</key>
    <false/>
    <key>identifier</key>
    <string>com.github.munki.pkg.isIllustrator18Installed</string>
    <key>install_location</key>
    <array>
        <string>/</string>
    </array>
    <key>name</key>
    <string>isIllustrator18Installed-${version}.pkg</string>
    <key>ownership</key>
    <string>recommended</string>
    <key>postinstall_action</key>
    <string>none</string>
    <key>suppress_bundle_relocation</key>
    <true/>
    <key>version</key>
    <string>1.0</string>
</dict>
</plist>

 

Add `product id` to a distribution pkg with Packages.app

Packages is a great GUI tool for creating distribution and flat .pkg installers for various needs in your environment.  Version 1.2.2 of Packages added the ability to add a product id to the pkg .dist file at build time.

Documented at https://managingosx.wordpress.com/2017/11/17/customized-high-sierra-install-issues-and-workarounds/ distribution-style packages need to have a unique product IDs included in the distribution file for it to work with startosinstall‘s --installpackage option. Without a product id the package is not included in the output of that tool.

To add a product id to a Packages project do the following:

1. In the “Packages->Preferences…->Advanced” settings tick the box to “Show Advanced User Options” 
2. Create a new Distribution Project. Access the “Project” listing on the left and in the “Settings” tab you’ll see “Advanced Options”. Scroll to the “product id”.
3. Once you build the pkg, the distribution file in the package will contain a product id. 

 

Configuring System Integrity Protection in a NetBoot environment

System Integrity Protection (SIP) can be enabled and disabled using csrutil from OS X Recovery per Apple’s documentation.  However, booting to Recovery is a local-only procedure and allows no remote access capabilities. I work remotely so it interests me to have capabilities to remotely change SIP status instead of walking a user thru the Recovery process which is daunting over the phone. We currently have NetBoot with Apple Remote Desktop (ARD) access in all offices and that can be leveraged for our needs.

The NetBoot environment by default doesn’t allow for csrutil access to enable or disable SIP: 

However, if we copy boot.efi from a Recovery partition and use it to replace the i386/booter file in the NetBoot NBI the NetBoot environment can adjust SIP’s status:

To extract the boot.efi first we have to determine which partition the Recovery OS is on and mount it. In this example the Recovery OS is on /dev/disk1s3 and is on an APFS formatted disk.  Use mount -t apfs /dev/disk1s3 /path/to/mountpoint to mount it to a mount point and copy the boot.efi file off:Now copy the boot.efi in the NBI’s i386/ directory, name it booter and give it 664 root:admin permissions:

Now when I NetBoot to that NBI I can gain access with ARD and adjust SIP status with csrutil.

APFS Disk Roles

APFS is Apple’s new file system coming sometime in 2017. In 10.12.x the disk management command line tools have been updated to recognize commands relating to APFS. diskutil has some APFS options, one of which being changeVolumeRole . In that verb there is a reference as to how to set the different roles the volume can be

From the manpage of diskutil:

changeVolumeRole | chrole volumeDevice roles
Change the role metadata flag bits of an existing
APFS Volume.

The roles should be any combination of one or more
of the characters busrvBUSRV in much the same man-
ner as diskutil apfs addVolume above, in which
unspecified flags are left alone, use of lower-case
causes flags to be cleared, and use of upper-case
causes flags to be set. Alternatively, clear will
remove all flags, or 0 can be used as a no-op for
scripting convenience. You should not make any
assumptions about the usage or legal combinations
of role bits.

Ownership of the affected disks is required.

But no where does it state what the roles BUSRV are.

The role of the disk can be observed by running diskutil apfs list

APFS Container (1 found)
|
+-- Container disk2 9C36DEF6-B883-462B-A227-84F8A60E3551
    ====================================================
    APFS Container Reference: disk2
    Capacity Ceiling (Size): 255883108352 B (255.9 GB)
    Capacity In Use By Volumes: 138276864 B (138.3 MB) (0.1% used)
    Capacity Available: 255744831488 B (255.7 GB) (99.9% free)
    |
    +-< Physical Store disk0s4 13E393EF-C27E-44EC-B238-A7CA8A842F50     | -----------------------------------------------------------     | APFS Physical Store Disk: disk0s4     | Size: 255883108352 B (255.9 GB)     |     +-> Volume disk2s1 CC9D66C2-345C-4415-92E4-8CDE3A396180
        ---------------------------------------------------
        APFS Volume Disk (Role): disk2s1 (No specific role)
        Name: apfTest
        Mount Point: /Volumes/apfTest
        Capacity Consumed: 24576 B (24.6 KB)
        Capacity Reserve: None
        Capacity Quota: None
        Cryptographic Security: None

Iterating thru the roles they translate to:

B = "Preboot"
U = "User"
S = "System"
R = "Recovery"
V = "VM"

A volume can be set with any combination of roles according to diskutil.

A volume with all roles set shows

APFS Volume Disk (Role):  disk2s1 (Preboot, User, System, Recovery, VM)

What’s New? New “What’s New” Office 2016 Suppression Key

Updated:
• Notification that one setting can suppress What’s New for the entire Office suite
• Changed to reflect new 15.34 key to suppress What’s New dialogs by a boolean
• Update to OneNote now using the same OUIWhatsNewShonItemIds key instead of its own ONWhatsNewShownItemIds key

My previous post, Not much, what’s new with you?, showed how to suppress the “What’s New” banners on updated software versions of the Office 2016 Suite.  While it worked, it _was_ work to get the specific preference key value to block the latest banner from appearing.  Due to the nature of how the values were dynamically created at build time it wasn’t known what those values were until the software was downloaded, installed, launched, then examine the preference file for the new value of OUIWhatsNewLastShownLink.  Blah.

Our good friends at Microsoft recognized the madness and worked on a way to make the suppression easier and more predictable for us admins.  As of version 15.32 there is a new key that takes an array of ints that can be added to the mobileconfig profile —  OUIWhatsNewShownItemIds.  The previous key OUIWhatsNewLastShownLink is still needed to suppress the What’s New dialogs prior to 15.32.

Good News, Bad News, Better News, Best News, and Bestest News

The Good News is that the values of OUIWhatsNewShownItemIds are predictable. It starts at 1 and increases by 1 for every new feature that is to be listed in a What’s New dialog box.  The Bad News is that each application can have its own number of new features to display, so knowing how many values isn’t known ahead of time. The Better News is that there is a bug (VSO #1476177 – Give admins a better way to turn off the What’s New dialog for O365 users) reported by our same Microsoft friends to recognize a boolean to “Don’t show me any more What’s New dialogs for any new versions ever.”  The Bestest News is that the new boolean value coming in version 15.34 can be set in the key ShowWhatsNewOnLaunch to be -bool false in the com.microsoft.office domain for the entire suite.  No need for individual application domain settings to suppress What’s New dialogs. That feature is on track to be part of the 15.34 release on May 16th.

So, until May 16th, you can add a list of values to the OUIWhatsNewShownItemIds key to suppress dialogs until the boolean value is respected.  The array must be a complete list meaning you can’t just add a value of 10 and have that mean block all values 1-10.

Each application domain (com.microsoft.Excel, com.microsoft.onenote.mac, com.microsoft.Outlook, com.microsoft.Powerpoint, and com.microsoft.Word) will need the values added for OUIWhatsNewShownItemIds. The easiest way would be to add these values to the existing mobileconfig profiles from Not much, what’s new with you? and modify it like this example for Word. But come version 15.34 just use the new key in the com.microsoft.office domain and call it a night.

Office 2016 Preference Management Changes

Starting with Office version 15.33 you’ll have the ability to manage some suite-wide preferences via profile management. Previously, these settings were configurable via defaults commands but weren’t CFPrefs enabled to allow for profile management of the settings. Thanks to the hard work of Paul Bowden and Erik Schwiebert at Microsoft, along with the collaboration and feedback of Mac admins in the macadmins.org slack instance, this request of preference management has been made possible. And this is just the beginning. Now with the foundation for preference management in code this will allow for more management options in future versions.

When an Office 15.33 app is launched for the first time, the existing preferences in ~/Library/Group Containers/UBF8T346G9.Office/com.microsoft.officeprefs.plist will be migrated over to the new preference domain automatically. At that time a key will be set signaling that the migration has occurred.

Paul has put together a new site (http://www.office4mac.com) that showcases a video course educating users and admins of the management changes. Look for more videos to come. This video shows examples of the preference changes, how to manage them, and implementing them through a management system. It’s definitely worth the watch.

For me, the meat and potatoes of these changes are the keys and values that are manageable in the com.microsoft.office domain. Here is an example management profile of all the keys that can be managed.

OfficeActivationEmailAddress adds a “Belongs to” value in the About box to list who owns the software.

DefaultsToLocalOpenSave – by default Office offers to open and save documents to OneDrive, however due to data security policies that may not be acceptable and confuse users. This key will set the default open and save dialog boxes of all Office apps to the standard System views.

VisualBasicMacroExecutionState has 3 values that relate to the “GUI settings” in Preferences->Security & Privacty in app:

DisabledWithWarnings – “Disable all macros with notification” (Default)

DisableWithoutWarnings – “Disable all macros without notification”

EnabledWithoutWarnings – “Enable all macros (not recommended; potentially dangerous code can run)”

I don’t recommend managing the HaveMergedOldPrefs key as that is set organically. If you set it to TRUE then the old pref won’t be migrated automatically on first run. If you manage it as FALSE then it will try and migrate on every launch.

The two debug keys msoridEnableLogging and msoridDefaultMinimumSeverity should only be set when debugging an issue and I don’t see a need to manage them centrally. Leaving them enabled isn’t recommended.

Seeing these preference options move to a manageable location is a big plus for us admins, not only for the specifics of these settings, but also in the willingness of Microsoft to make these changes based on admin feedback. This can only mean more good things in the future.

How to remove accounts cleanly

When you want to get rid of an account that’s not being used on a computer anymore, how do you do that pragmatically?  Visiting the computer and going thru the System Preferences’ Users & Groups options is time consuming, inconvenient, and sometimes physically not possible.

Previously I’d say use dscl to remove the cached account credentials and rm -r /Users/username to remove the home folder.  However, that leaves behind pieces that has caused some issues.

Enter sysadminctl

This removes any running processes by that user, the home folder, the public share, the cached credentials, and disabling Back To My Mac for that user if set.

Example:

bash-3.2# ls /var/db/dslocal/nodes/Default/sharepoints/
Tester's Public Folder.plist eholtam's Public Folder.plist admin's Public Folder.plist

bash-3.2# sysadminctl -deleteUser tester
2017-03-14 21:28:05.241 sysadminctl[2093:60392] Killing all processes for UID 503
2017-03-14 21:28:05.242 sysadminctl[2093:60392] Removing tester's home at /Users/tester
2017-03-14 21:28:05.877 sysadminctl[2093:60392] Deleting Public share point for tester
2017-03-14 21:28:05.903 sysadminctl[2093:60392] Deleting record for tester
2017-03-14 21:28:05.930 sysadminctl[2093:60392] AOSKit INFO: Disabling BTMM for user, no zone found for uid=503, usersToZones: {
 502 = "1234567.members.btmm.icloud.com.";
}

bash-3.2# ls
eholtam's Public Folder.plist admin's Public Folder.plist

Future me will be using sysadminctl for all account deletion needs.

Sierra’s Built-in Storage Management Utility

New with Sierra there is a built-in utility to help keep disk storage space available.  The function is part of the System Information.app and is accessed a few ways:

1.  => About This Mac => Storage => Manage…
2. (Hold the option key down)  => System Information… => Window => Storage Mangement (Cmd-U)
3. /Applications/Utilities/System Information.app => Window => Storage Mangement (Cmd-U)

Once launched it will proceed to gather data sizes of categories of interest. The available and total disk space will be listed in the window’s name.

First you’ll see some recommendations of ways to keep disk space available.  Each has its own set of gotchas so be sure to make note of the implications:

Store in iCloud —

There has been some interesting discoveries in the behavior surrounding iCloud Desktop and Documents.  See iCloud Desktop and Documents in macOS Sierra – The Good, The Bad and the Ugly for a full rundown. Even though these checkboxes are checked by default, that doesn’t represent the actual state of the setting.  On my machine I have Desktop and Documents turned off in the iCloud preference pane yet this box shows as checked.

Optimize Storage —

Empty Trash Automatically —

If you’re one of those that can’t commit to deleting things once put in the Trash, let the OS handle it for you.

Reduce Clutter —

This option opens the Documents listing.

Along the left are categories and the amount of space each is taking up.  Accessing those brings up a list sorted by largest on top.  If you want to remove an individual listing, right click and select Delete. Even though Applications are listed, non-admins can’t remove applications without admin credentials.

Thanks to @adamcodega for pointing this tool out.