YubiKey smart card login with Open Directory
Yubico sells Mac-compatible USB authentication keys for two-factor authentication. Its YubiKeys support a slew of authentication mechanisms. I just started working with their FIPS-validated key for one of my clients. Yubico’s FIPS keys appear to be functionally equivalent to their YubiKey 4 series. (Yubico is currently selling the 5 series for those customers without a need for FIPS compliance.)
The YubiKey officially supports two methods to log into macOS. One method uses a Yubico PAM which needs to be installed on the Mac. This PAM uses the Yubico HMAC-SHA1 challenge-response mechanism. The second method uses the macOS native PIV smart card framework. The PAM method requires that all accounts on the Mac use the key for authentication. In other words, two-factor authentication is required for every account on the system. The smart card method allows selected accounts to be paired with keys, and the use of 2FA is optional with each paired account. As of High Sierra 10.13.2, smart card-only authentication can be configured, across all accounts. I have been testing the smart card mechanism in my lab.
Setting up the YubiKey with a local user account is incredibly simple. Once the certificates are set up on the key and the key is inserted, macOS asks the user if she would like to pair the “SmartCard” to the logged in account. However, I ran into a problem when I wanted to join an Open Directory network user account to the key:
Bummer. It appears that the built-in pairing mechanism works with the local Open Directory, but not a networked Open Directory on macOS Server. (I got this error whether the Mac was bound to the directory or not.) YubiKey provides no support or documentation on using networked Open Directory with its keys. Apple provides documentation (below) on how to set up attribute matching between a directory and smart card certificates. I haven’t tried this mechanism yet.
With a bit of reverse engineering, I figured out a quick way to manually pair the key with an Open Directory network account. This uses the same technique as the built-in pairing mechanism – a hash of the public key inserted into the user’s directory entry. Disclaimer: While this technique seems to work, it’s untested. Don’t assume that this is a secure, complete, or production-ready solution. Any use of this procedure is at your own risk. The purpose of this blog post is to provide information for the Mac security engineering community, collaborate, and share experiences. Now that we’ve satisfied the lawyers…
Network user pairing using public key hash
1. Insert the YubiKey (provisioned with Mac login certificates) into a Mac. On the command line, enter: security export-smartcard
2. In the output, look for the label “Certificate For PIV Authentication (Yubico PIV Authentication)”. You’ll find an attribute pkhh. This is the hash value you want (without the spaces or brackets).
3. Using Directory Utility on macOS Server, enter the Directory Editor and authenticate as diradmin.
4. In the network user account you’d like to tie to the key, add the following value to the attribute AuthenticationAuthority: ;tokenidentity;[hash value from step 2]
5. Save the user’s directory record.
On a network-joined Mac’s login screen, you should be prompted for the key’s PIN after inserting it.