Using Your YubiKey as a Smart Card in macOS


To use your YubiKey to securely log in to your Mac, follow the instructions below.

How To Use Your YubiKey as a Smart Card with macOS

Requirements

Personalizing the YubiKey PIV application

Note: The default settings on the YubiKey PIV application are as follows:

  • PIN: 123456 (6-8 characters allowed, macOS requires numeric-only)
  • PUK: 12345678 (6-8 characters allowed)
  • Management Key: 010203040506070801020304050607080102030405060708

If you have forgotten your PIN and need to reset the PIV application to default, refer to this article.

Setting a new PIN

  1. In YubiKey Manager, click Applications > PIV
  2. Click Configure PINs
  3. Click Change PIN
  • Current PIN: Assuming the default PIN has not been changed, enter the default PIN of 123456 or simply click Use default.
  • New PIN: Use a 6-8 digit number for your new PIN and note it for future reference. Do not use letters or other characters in your PIN when configuring for macOS login. macOS does not accept non-numeric characters.
  • Confirm new PIN: Confirm the PIN entered in the previous field.
  1. Click Change PIN

Setting a new PUK

  1. On the Configure PINs screen, click Change PUK
  • Current PUK: Assuming the default PUK has not been changed, enter the default PUK of 12345678 or simply click Use default.
  • New PUK: Use a 6-8 digit number for your new PUK and note it for future reference.
  • Confirm new PUK: Confirm the PUK entered in the previous field.
  1. Click Change PUK

Setting a new Management Key

  1. On the Configure PINs screen, click Change Management Key
  • Current Management Key: Assuming the default Management Key has not been changed, enter the default Management Key of 010203040506070801020304050607080102030405060708 or simply click Use default.
  • New Management Key: Enter a new 48 character Management Key, or choose Generate to create a randomized Management Key.
  • Protect with PIN: Choose this option if you prefer the Management Key to be encrypted using the PIN. When prompted for the Management Key in the future, the PIN can be provided in place of entering a 48 character Management Key. Considering the Management Key must be entered when configuring your YubiKey for macOS account login, this option is highly recommended.
  1. Click Finish. If you chose Protect with PIN, enter your PIN in the PIN field and click OK.

Configuring your YubiKey for macOS account login

  1. In YubiKey Manager, click Applications > PIV
  2. Click Setup for macOS
  3. Click Setup for macOS. If you chose Protect with PIN when setting the Management Key, enter your PIN in the prompt. If you set a custom Management Key and did not protect with PIN, enter the Management Key in the prompt.
  4. Click OK.
  5. Remove your YubiKey and plug it into the USB port
  6. In the SmartCard Pairing macOS prompt, click Pair. Note: If this prompt doesn't appear, see the Troubleshooting and Additional Topics section below.
  7. In the password prompt, enter the password for the user account listed in the User Name field and click Pair
  8. In the SmartCard Pairing prompt, enter the PIN for your YubiKey (refer to the Setting a new PIN section above) and click OK
  9. In the "login" keychain prompt, enter your keychain possible (typically the password for the logged in user account) and click OK

To test the configuration, lock your Mac (Ctrl+Command+Q), and make sure the password field reads PIN when your YubiKey is inserted. Try unlocking your session with your YubiKey by entering your PIN.

How to Unpair Your YubiKey and PIV Login from macOS

Warning: Unpairing your YubiKey from macOS does not disable the smart requirement, so if you enabled this requirement, you should first disable it before unpairing your YubiKeys, to ensure you do not get locked out. The profile that enables the smart card requirement can be removed via System Preferences > Profiles (note that Profiles will not appear unless you have a profile installed). For more information, see this Apple article under the section Disable smart card-only authentication. If you did not enable the smart card requirement, disregard this warning.

To unpair your PIV login from macOS, follow the procedures below. You can choose to delete all certificates that were installed on your YubiKey when you paired the device with macOS, or only the certificates that were added for logging in to macOS. Also included are reset instructions so that macOS will no longer prompt you to pair your YubiKey or a smart card whenever the device(s) are detected.

Removing Certificates from the YubiKey

To delete all of the certificates on the YubiKey

Use this procedure if you want to reset the PIV application, which will remove all certificates and reset the PIN, PUK, and Management Key to default values. If you want to keep your certificates, skip to the next procedure.

  1. In YubiKey Manager, click Applications > PIV
  2. Click Reset PIV
  3. Click Yes to confirm

To delete only the certificates created after completing the macOS login instructions

Use this procedure if you want to remove only the certificates created for macOS login.

  1. In YubiKey Manager, click Applications > PIV
  2. Click Configure Certificates
  3. On the Authentication tab, click Delete
  4. Click Yes to confirm certificate deletion. If prompted for the PIN, enter the PIN an click OK. If prompted for the Management Key, provide the Management Key and click OK.
  5. On the Key Management tab, click Delete
  6. Click Yes to confirm certificate deletion. If prompted for the PIN, enter the PIN an click OK. If prompted for the Management Key, provide the Management Key and click OK.

Removing the Smart Card Pairing from macOS 

To remove a single YubiKey or smart card from macOS login

  1. Open Terminal.
  2. Run: sc_auth list [username]
    • ex: sc_auth list john
  3. Highlight and copy (Command+C) the hash listed for your user.
    • If multiple YubiKey smart cards are paired with your account and you aren't sure which hash is which, you can check the hash of a particular YubiKey by running sc_auth identities with the key in question plugged in.
  4. Run: sc_auth unpair -h [hash]

To remove all paired YubiKeys and smart cards for a single user

  1. Open Terminal.
  2. Run: sc_auth unpair -u [username]
    • ex: sc_auth unpair john

To remove all paired YubiKeys and smart cards for the currently logged in user

  1. Open Terminal.
  2. Run: sc_auth unpair -u $(whoami)

To turn off the pairing user interface in macOS

Use this option if you want to insert your YubiKey that contain certificates, and you do not want macOS Sierra to prompt you to pair it to your account.

  1. Open Terminal
  2. Run: sc_auth pairing_ui -s disable 

Note: The pairing UI can be re-enabled with the command sc_auth pairing_ui -s enable

Troubleshooting and Additional Topics

SmartCard pairing prompt does not appear

Sometimes, the pairing prompt referenced in step 6 under Configuring your YubiKey for macOS account login will not appear. If this happens, follow the steps below in order.

  • The Pairing UI in macOS may be disabled. To try enabling it, run the following command in Terminal: sc_auth pairing_ui -s enable. To check the status of the Pairing UI, run sc_auth pairing_ui -s status. Once the UI has been enabled, reinsert your YubiKey.
  • If that doesn't help, try reinserting your YubiKey a few additional times and see if that causes the pairing prompt to appear.
  • If the pairing prompt still does not appear, with your YubiKey inserted, try running the following command in Terminal: sc_auth pairing_ui -f.
  • If the above command does nothing, still with the YubiKey inserted, try running sc_auth identities (in Terminal). This will check whether you Mac detects any unpaired smart cards. If it does, the output of the command should look something like the following.
SmartCard: com.apple.pivtoken:2D2248DE2F337A1F99C34BE4DCF44B61 Unpaired identities: A205691C39CBE2FF81F72070C8FEE6B27DF4E527    Certificate For PIV Authentication (Yubico PIV Authentication)
  • If you see this, you can manually pair your smart card using the following (Terminal) command, replacing <hash> with the long string from the sc_auth identities output (A205691C39CBE2FF81F72070C8FEE6B27DF4E527 in the above example): sudo sc_auth pair -h <hash> -u $(whoami).
  • If sc_auth identities doesn't yield any output on the other hand, consider resetting your YubiKey's PIV smart card application and following through the steps in this article again from the beginning.

Requiring your YubiKey Smart Card

By default, a paired smart card can be used as an alternative way to log in (instead of a password), but it is not required.

This Apple article covers configuring your Mac so a paired smart card is required for various activities (namely, logging in and sudo).

Warning: Requiring a smart card for authentication can result in a system lockout if performed incorrectly. Reading the recovery section (Disable smart card-only authentication) in the previously linked Apple article is advised before making configuration changes, as is registering at least two smart cards, and verifying that they both can be used to authenticate (log in to/unlock your account).

FileVault Configuration

If you do not use FileVault for full-disk encryption (FDE), this topic does not apply to you. Note that if your Mac has been upgraded to macOS Catalina, FileVault FDE may have been turned on automatically.

FileVault does not support smart cards for authentication, meaning you will still need to use your password to unlock your FileVault-encrypted disk.

By default, when a user enters their password to decrypt the FileVault disk at boot, this password will be passed through and a smart card will not be used for login, even if you configure it to be required. To change this so that the user will not automatically be logged in and will be shown the login screen, run the command below in Terminal.

sudo defaults write /Library/Preferences/com.apple.loginwindow DisableFDEAutoLogin -bool YES

Multiple YubiKeys, Macs, etc.

Using the same YubiKey smart card on multiple Macs for logging in:

  • Once you have set up your YubiKey on the first Mac, on each other Mac, simply plug in your YubiKey and follow steps 6-9 in the section Pairing your YubiKey with macOS.

Using the same YubiKey smart card for multiple accounts on a single Mac:


  • On a single Mac, macOS only allows you to associate a given YubiKey with one user account.

Using multiple YubiKeys with the same user account on a single Mac:

  • For any additional YubiKeys beyond the first, simply follow through the steps in this guide again. Once this has been done for all YubiKeys, any of them should be able to log you in to/unlock your Mac when you provide the PIN. Note that the PIN may be different for each YubiKey, depending on how you set them up.

Lost or stolen YubiKey

  • If you followed these instructions to require a paired smart card for login, follow the steps in the same guide under the section Disable smart card-only authentication.
  • If you have not set up your Mac to require a smart card, then the YubiKey is not required, so you should still be able to log in to your Mac without a YubiKey by entering your normal account password (following the steps in this guide will not change your normal account password). To unpair the lost or stolen YubiKey, follow the section above titled How to Unpair Your YubiKey and PIV Login from macOS.