1. Yubico
  2. Business
  3. Guides

YubiKey for macOS login: Advanced topics

Avatar
Chris Halos
Created - Updated

 

bulb-light-icon.svg Tip: This article is intended as a companion to the YubiKey for macOS login article. If you're looking for instructions to set up your YubiKey to login to macOS, review that article before consulting this article.

Table of Contents

Troubleshooting and advanced topics

          Smart card pairing prompt does not appear

          Manually pairing a smart card without the Pairing UI

          Requiring your YubiKey smart card

          FileVault configuration

                    Intel-based Macs

                    Apple silicon Macs

          Multiple YubiKeys, Macs, etc.

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

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

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

          Lost or stolen YubiKey

How to unpair your YubiKey from your macOS account

          Removing the smart card pairing from macOS

                    To remove a single YubiKey or smart card from macOS login

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

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

                    To turn off the pairing user interface in macOS

          Removing certificates from the YubiKey

                    To delete all of the certificates on the YubiKey

                    To delete only the certificates created for macOS account login

 

Troubleshooting and advanced topics

Smart card pairing prompt does not appear

Sometimes, the pairing prompt referenced in Pairing your YubiKey to your macOS account (final section in YubiKey for macOS login) will not appear. If this happens, follow the steps below in order.

 

  • To check the status of the Pairing UI, run the following command in Terminal:
    sc_auth pairing_ui -s status
  • The Pairing UI in macOS may be disabled. To try re-enabling it, run the following command in Terminal: 
    sc_auth pairing_ui -s enable
  • Once the Pairing UI has been enabled, reinsert your YubiKey.
  • If that doesn't help, try re-inserting 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

 

Manually pairing a smart card without the pairing UI

If the SmartCard Pairing UI is enabled and the YubiKey has certificates in 9a and 9d, but the Smartcard Agent popup doesn't appear when the YubiKey is plugged in, follow the troubleshooting steps below:

  1. Open the macOS Terminal
  2. Enter the following command and press return:
     
    sc_auth identities

    If certificates are present on the YubiKey but the YubiKey isn't paired to the user account, an unpaired identity should show as a result, as shown below:
    The hash will be different for you, but B25AABF7F5F9B7C6BEE641D663D8E52C90BC7AB4 will be used in the example.
  3. Run the following command, changing the hash to match what you received in step 2:
    sudo sc_auth pair -h <your hash> -u $(whoami)
    Example:
    sudo sc_auth pair -h B25AABF7F5F9B7C6BEE641D663D8E52C90BC7AB4 -u $(whoami)
  4. Run the following command to confirm that the identity is now paired to your user account: 
    sc_auth identities

  5. With the paired YubiKey plugged in, confirm macOS prompts you to login with the YubiKey by locking the computer (control-command-Q). 
  6. Enter the YubiKey smart card PIN to unlock the account.

Requiring your YubiKey smart card

Apple silicon Mac users: Because of some differences in the way smart card authentication works on Macs with Apple silicon CPUs (versus those with Intel), consumers and individuals should understand that requiring a smart card for MacOS login can result in a system lockout if performed incorrectly. Additionally, requiring smart cards for login on Apple silicon Macs also requires the use of smart cards to unlock FileVault. Each time the computer is shut down, macOS uses the last used smart card to lock the disk with FileVault. In this scenario, only the last smart card used to login will work to unlock the disk upon next startup, effectively making any smart cards set up as backups incapable of unlocking the disk. As such, this solution is targeted primarily towards corporate enterprises that have implemented both a centrally managed CA for certificate lifecycle management and an endpoint management system that provides an account recovery process for locked-out users.
Warning: Requiring a smart card for authentication can result in a system lockout if performed incorrectly. Yubico is not responsible for any system lockout that occurs as a result of requiring smart cards on your Mac. If you have locked yourself out of your Mac by requiring a smart card and the resources on this page have not helped to get you back in, you will need to contact Apple for further assistance. 

Before making any configuration changes, please:

* Read this Apple support article, especially the section Disable smart card-only authentication.

* Register at least two smart cards and verify that both are working for authentication (to log in to / unlock your account), and refer to the special considerations described when using Apple silicon Macs under the FileVault Configuration > Apple silicon Macs section in this article.

 

FileVault configuration

FileVault is macOS' built-in full-disk encryption solution.

 

Intel-based Macs

On Intel-based Macs, FileVault does not support smart cards for pre-boot authentication, meaning you will still need to use your password to unlock your FileVault-encrypted disk. This is the first password prompt you receive after starting your Mac from a powered-off state.

 

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 (a second authentication prompt), run the command below in Terminal.

 

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

 

Apple silicon Macs

On Apple silicon Macs, smart cards are now supported for pre-boot FileVault authentication. Since a Mac's encrypted data has yet to be unlocked during this authentication, only the smart card that was used most recently to authenticate will work. This effectively makes any smart cards set up as backups incapable of unlocking the disk. As such, this solution is targeted primarily towards corporate enterprises that have implemented both a centrally managed CA for certificate lifecycle management and an endpoint management system that provides an account recovery process for locked-out users. Consumers and individuals should understand that requiring a smart card for MacOS login can result in a system lockout if performed incorrectly.

 

If you are not sure whether your Mac has an Intel or Apple silicon processor, please see this article.

 

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 the pairing prompts (if the pairing prompt doesn't appear, refer to Smart card pairing prompt does not appear).

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 YubiKey for macOS login 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. Additionally, note the caveat above regarding Apple silicon Macs for pre-boot FileVault authentication and only the most recently used smart card working to unlock the encrypted disk.

Lost or stolen YubiKey

  • If you followed these instructions to require a paired smart card for login, follow the steps in the same article under 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, see Removing the smart card pairing from macOS.

 

How to unpair your YubiKey from your macOS account

Warning: Unpairing your YubiKey from macOS does not disable the smart card 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 smart card 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 the smart card pairing from macOS 

To remove a single YubiKey or smart card from macOS login

    1. Open Terminal.
    2. Run the following command:
      sc_auth list [username]
      Example: 
      sc_auth list john
    3. Highlight and copy (Command+C) the hash listed for your user account
      manual-icon.svg Note:  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 the following command with the key in question plugged in:

      sc_auth identities
      Run the following command: 
      sc_auth unpair -h [hash]

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

  1. Open the macOS Terminal
  2. Run the following command:
    sc_auth unpair -u [username]
    Example:
    sc_auth unpair john

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

  1. Open the macOS Terminal
  2. Run the following command:
    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 to prompt you to pair it to your user account.

 

  1. Open the macOS Terminal
  2. Run the following command:
    sc_auth pairing_ui -s disable
     
manual-icon.svg Note: The pairing UI can be re-enabled at any time by running the following command in Terminal:
sc_auth pairing_ui -s enable

 

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 Yubico Authenticator, ensure you are on the Home screen
  2. Click Factory reset (located under the kebab menu if it isn't expanded)
  3. Click PIV only
  4. Click Reset to reset the PIV application on your YubiKey

To delete only the certificates created for macOS account login

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

  1. In Yubico Authenticator, click Certificates
  2. On the Certificates tab, click Authentication (9a)
  3. Click Delete certificate/key
  4. Click Delete to confirm certificate deletion. If prompted for the PIN, enter the PIN and click OK. If prompted for the Management Key, provide the Management Key and click OK.
  5. On the Certificates tab, click Key Management (9d)
  6. Click Delete certificate/key
    Screenshot 2025-03-03 at 4.14.55 PM.png
  7. Click Delete to confirm certificate deletion. If prompted for the PIN, enter the PIN and click OK. If prompted for the Management Key, provide the Management Key and click OK.
manual-icon.svg Note: 
The YubiKey Bio Multi-protocol Edition supports using fingerprint verification in lieu of the PIN when performing cryptographic operations. In the case of PIV smart card however, to provide users with this fingerprint option, client software or middleware is required. Yubico has implemented support for this in the Yubico Minidriver from version 4.6.1 (only available for Windows OS). If users attempt to use PIV smart card on the YubiKey Bio Multi-protocol Edition without supporting middleware, they will encounter limitations.

In scenarios where supporting middleware is not available or not utilized, users can still access the PIV application on the YubiKey Bio Multi-protocol Edition. However, they will not have the option to utilize fingerprint authentication for cryptographic operations. Instead, they will need to rely on traditional methods such as entering a PIN.

While users can still access the PIV application and perform cryptographic operations, they miss out on the convenience and potentially enhanced security offered by biometric authentication. Without the fingerprint option, users may need to rely on the PIN.