Using YubiKey with macOS

Content

• Applicable YubiKey
• Introduction
• Installation
• Configuration
  • Configuring Your YubiKeys
  • Associating Your YubiKeys with Your Account
  • Testing the Configuration
  • Enabling the Configuration
• Troubleshooting
• Uninstalling the macOS Login Tool
• Notes

Applicable YubiKey

(Up)
YubiKey 5 NFC, YubiKey 5 Nano, YubiKey 5C, YubiKey 5C Nano, YubiKey NEO, YubiKey 4, YubiKey 4 Nano, YubiKey 4, YubiKey 4C Nano.

Introduction

(Up)
The macOS Login Tool allows for secure two-factor authentication on Macs using the HMAC-SHA1 challenge-response feature of the YubiKey.

Note: Enabling full disk encryption (FDE) with FileVault is highly recommended when using the macOS Login Tool. If you do not enable FDE, it is possible to reboot the Mac into recovery mode and disable the 2FA requirement.

Installation

(Up)

1. Download the Yubico PAM.
2. Double-click the downloaded .pkg file to start the installation.
3. Click Continue.
4. Click Install.
5. When prompted, enter your password or use Touch ID to confirm the installation.
6. ClickCloseto exit the installation wizard.

Configuration

(Up)

Configuring Your YubiKeys

You will need software to set up YubiKey Manager.

1. Open YubiKey Manager.
2. Insert your YubiKey to an available USB port on your Mac.
3. Click Applications, then OTP.
4. Under Long Touch (Slot 2)click Configure.
5. Select Challenge-response and click Next.
6. Click Generate, to generate a new secret.
7. (Optional) Check theRequire touchoption if you want to require a touch to the metal contact on the YubiKey to approve challenge-response actions.
8. Click Finish.

Repeat these steps for any additional YubiKeys that you want to use. It is highly recommended to set up a spare YubiKey in order to be able to access your Mac in case the main YubiKey is lost or broken.

Associating Your YubiKeys with Your Account

(Up)

1. Open Terminal.
2. Insert your YubiKey to an available USB port on your Mac.
3. Run the command: ykpamcfg -2.
   • If you previously checked the Require touch option, then when the indicator on the YubiKey starts flashing, touch the sensor button on the key.

Repeat these steps for any additional YubiKeys that you want to use.

Note: If you receive an error similar toFile /Users/username/.yubico/challenge-7122584 already exists, refusing to overwritethis indicates you have already associated this YubiKey with your account. If you are reconfiguring the YubiKey with a new challenge-response secret, you need to delete this file before running the ykpamcfg -2command.

Testing the Configuration

(Up)
Before you enable mandatory two-factor authentication on your Mac, you should verify that the configuration works. This is achieved by enabling the requirement only for the screensaver first; if something goes wrong and it does not work you can reboot your Mac and log in normally with just your password.

To get started, make sure your Mac is set to require a password as soon as the screen saver starts.

1. Open System Preferences.
2. Click Security & Privacy.
3. Click on the General tab.
4. Check the Require password option and select immediately.

Now the Mac can be configured to require two-factor authentication for the screensaver.

1. Open Terminal.
2. Run: sudo nano /etc/pam.d/screensaver
3. When prompted, type your password and press Enter.
4. Add the line below above the account required pam_opendirectory.so line.

auth required /usr/local/lib/security/pam_yubico.so mode=challenge-response

5. Press Ctrl+X, Y, and then Enter, to save the file.

To test the configuration, press Command+Ctrl+Q to lock the Mac. Make sure your YubiKey is not plugged in to the Mac and attempt to login; you should not be able to login, even with the correct password. Then plug in the YubiKey and make sure you can log in after entering the correct password.

Enabling the Configuration

(Up)
Once you’ve verified that the configuration works, follow the step-by-step instructions below to enable two-factor authentication for the login screen, as well as for the screen saver.

1. Open Terminal.
2. Run: sudo nano /etc/pam.d/authorization
3. When prompted, type your password and press Enter.
4. Add the line below above the account required pam_opendirectory.so line.

auth required /usr/local/lib/security/pam_yubico.so mode=challenge-response

5. Press Ctrl+X, Y, and then Enter, to save the file.

Troubleshooting

(Up)
If you run into issues with the macOS Login Tool after following this guide, you can follow the steps below to enable debug logging, which will provide insight into the issue.

1. Open Terminal.
2. Run: sudo touch /var/log/pam_yubico.log
3. Run: sudo chmod 766 /var/log/pam_yubico.log
4. Run:sudo sed -i “.yubibak” -E “s/^auth.+pam_yubico\.so.+mode=challenge-response/& debug debug_file=\/var\/log\/pam_yubico.log/” /etc/pam.d/screensaver
5. Run:sudo sed -i “.yubibak” -E “s/^auth.+pam_yubico\.so.+mode=challenge-response/& debug debug_file=\/var\/log\/pam_yubico.log/” /etc/pam.d/authorization
6. Attempt to login with the YubiKey plugged in to your Mac.

You can analyze the /var/log/pam_yubico.log file to see where the issue is. Or contact Yubico support and submit the log data.

Uninstalling the macOS Login Tool

(Up)
You can use the script in the Uninstalling the macOS Login Toolarticle to uninstall the tool from your Mac.

1. Open Terminal.
2. Run: cd ~/Downloads
3. Run: sudo bash uninstall-maclogintool.sh
4. When prompted, press Enter to confirm the deletion.

Notes

(Up)

• Enabling the macOS Login Tool is a system-wide change and will affect all accounts on the Mac.
• If Touch ID is enabled, login will be done without Yubico PAM. Due to how Touch ID was implemented.