Suppressing Keyboard Setup Assistant

Jan 29, 2023

Researching Keyboard Setup Assistant started as an exercise in suppressing it during a demonstration video of our Mac provisioning process. My findings quickly became part of that very provisioning process.

Background

macOS presents Keyboard Setup Assistant when it encounters an unknown 3rd party keyboard. The assistant guides the user to press a couple of keys on the unknown keyboard and guesses the keyboard’s type: ANSI (United States), ISO (European), or JIS (Japanese). If the user closes KSA when it appears, it chooses ANSI. KSA also appears if you attach a peripheral that acts as a keyboard, such as a barcode scanner or a security key. (Quite honestly, I find KSA to be an annoyance.)

Technical Details

KSA persists the keyboard’s type in /Library/Preferences/com.apple.keyboardtype.plist (“the plist”). That plist contains a key named keyboardtype. In the keyboardtype dictionary, the key is an identifier and the value is an integer representing the type.

The identifier appears consistent across different Mac models and macOS versions. It is built from other identifiers found in IOKit. My Microsoft Sculpt Ergonomic (wireless) has an identifier of 1957-1118-0. 1957 is the ProductID. 1118 is the VendorID.

For the type, 40, 41, and 42 represent ANSI, ISO, and JIS respectively.

Discovering Keyboard Identifiers

When a keyboard’s identifier and corresponding type is known, it can be populated in the plist prior to KSA appearing.

The best way I found to discover the identifier and type was to was attach the keyboard to a clean test system.
First, discover the state of the plist. (It may not exist yet as it’s not in a default macOS install.)
defaults read /Library/Preferences/com.apple.keyboardtype.plist
Attach the keyboard and complete KSA.
Read the plist again. There should be a new entry for the keyboard.

Implementation

As mentioned above, it’s not just keyboards that trigger KSA. Keyboard-like devices such as barcode readers and security keys trigger it too. These types of device don’t have any keys to that KSA can use to detect the type. (One should just close KSA.) I realized that this research had a broader application at work where we use YubiKeys for MFA. By pre-populating the plist I could suppress KSA whenever we enroll a user’s new YubiKey. I gathered up all the YubiKey types we use and used the method above to learn their identifiers — only to discover they all had the same identifier.

The zsh script below is now part of our provisioning process. Other keyboards can be easily added as needed.

#!/bin/zsh

declare -A KEYBOARDS

KEYBOARDS[1031-4176-0]=40 # YubiKey
KEYBOARDS[1957-1118-0]=40 # Microsoft Sculpt Ergonomic
KEYBOARDS[219-1118-0]=40  # Microsoft Natural Ergonomic Keyboard 4000


for ID TYPE in "${(@kv)KEYBOARDS}"; do
    defaults write /Library/Preferences/com.apple.keyboardtype.plist keyboardtype \
    -dict-add "$ID" -integer $TYPE
done

macadmin.fraserhess.com