YubiKey for macOS login

Table of Contents

Requirements

Personalizing the YubiKey PIV application

          Setting a new PIN

          Setting a new PUK

          Setting a new Management Key

Preparing your YubiKey for macOS account login

Pairing your YubiKey to your macOS account

Requirements

• macOS 13 Ventura or newer (OS must be supported by Apple)
• Admin account
• Yubico Authenticator

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.

The PIV PIN and FIDO PIN are distinct and changing your PIV PIN will not affect your FIDO PIN (users typically set the same PIN for both applications for usability.

1. In Yubico Authenticator, click Certificates
   
2. Click Change PIN
   
3. Enter new PIN values
   

Current PIN: Assuming the default PIN has not been changed, the application should fill the default PIN for you.

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 PIN: Confirm the PIN entered in the previous field.

4. Click Save to set the new PIN

Setting a new PUK

1. In Yubico Authenticator, click Certificates
   
2. Click Change PUK
   
3. Enter new PUK values
   

Current PUK: Assuming the default PUK has not been changed, the application should fill the default PUK for you.

New PUK: Use a 6-8 digit number for your new PUK and note it for future reference.

Confirm PUK: Confirm the PUK entered in the previous field.

          4. Click Save to set the new PUK

Setting a new Management Key

1. In Yubico Authenticator, click Certificates
   
2. Click Management key
   
3. Enter the new management key
   

Current management key: Assuming the default Management Key has not been changed the application should fill the default management key for you.

New management key: Enter a new 48 character Management Key, or click the refresh button to create a random 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.

   4. Click Save

Preparing your YubiKey for macOS account login

1. In Yubico Authenticator, click Certificates
   
2. Confirm you have 9a Authentication selected
3. Click Generate Key to generate a new self-signed certificate
4. Fill out the Subject field with CN=MacOS login or whatever distinguished name you prefer, as long as the name follows the RFC 4514 specification
   
   

    Note:  By default the expiration date is set to 1 year from creation of the certificate. If you'd like to extend the expiration date, click the expiration date and change it before continuing.

5. Click Save and confirm you have a certificate in slot 9a of the YubiKey
6. Click on 9d Key Management
   
7. Click Generate Key to generate a new self-signed certificate
8. Fill out the Subject field with CN=encryption or whatever distinguished name you prefer, as long as the name follows the RFC 4514 specification
   
   

    Note:  By default the expiration date is set to 1 year from creation of the certificate. If you'd like to extend the expiration date, click the expiration date and change it before continuing.

9. Click Save and confirm you have a certificate in slot 9d of the YubiKey

Pairing your YubiKey to your macOS account

1. Disconnect and re-insert your YubiKey to pair it to the currently logged in user account. You should see the following alert at the top right of your screen. If you don't, refer to the Manually pairing a smart card without the Pairing UI section of the YubiKey for macOS login: Advanced topics article, for troubleshooting steps. 
   
2. Click the notification shown above to open the pairing prompt
   
3. Click Pair
   
   
4. Enter the password for your user account (must have administrator permissions), and then click Pair
   
   
5. Enter the PIN you created in step 3 of Setting a new PIN, and then click OK
   
6. Enter the keychain password (typically the same as your user account password), and then click OK. The smart card should now be usable for account login. You can test by locking your Mac (control+command+Q) and confirming you are now prompted for a PIN (with your YubiKey inserted) rather than your user account password. If the YubiKey is removed while at the login screen, the PIN prompt should change back to a password prompt.

 Tip: If you're having trouble with this process, or want to review advanced topics, refer to the companion to this article, YubiKey for macOS login: Advanced topics.

 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.