Using Your YubiKey as a Smart Card in macOS

Applicable Products


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, the Pairing UI in macOS may be disabled. Open the Terminal application in macOS and enter the following command: sc_auth pairing_ui -s enable
  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.

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), skip this section. Note that if your Mac has been upgraded to macOS Catalina, FileVault FDE may have been turned on automatically.

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

How to Unpair Your YubiKey and PIV Login from macOS

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

Frequently Asked Questions

  • Do I still need to authenticate and unlock my disk using my FileVault password using YubiKey on macOS?

Yes, you still need to authenticate and unlock your disk using your FileVault password. FileVault encrypts your Mac disk, but to gain access to your data you need to provide a password to decrypt the disk. The smart card implementation on macOS is separate from FileVault.

  • Can I use the same YubiKey as a Smart Card on multiple Macs?

Yes, 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.

  • Can I use the same YubiKey as a Smart Card for multiple accounts on a single Mac?

No, using the YubiKey as a smart card in macOS only allows you to associate the YubiKey to a single user account on that computer.

  • Can I use multiple YubiKeys with the same macOS account (on a single Mac)?

Yes, to do this, follow through the section Configuring your YubiKey for macOS account login again for each YubiKey. 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.

  • What happens if I lose all of my associated YubiKeys?
    • If you followed these instructions to require a paired smart card for login, follow the steps in 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).

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.