1. Yubico
  2. Business
  3. Guides

macOS Login Tool Configuration Guide [Deprecated]

Avatar
Clay Degruchy
Created - Updated

Due to developments outside of Yubico’s control, this tool cannot function on macOS Catalina (10.15) and newer. Apple has changed entitlements in authorization and added extra protections to the login process, which prevents it from communicating with USB devices (including the YubiKey). Because this prevents the macOS Login Tool from functioning under macOS Catalina, we will be discontinuing support for the macOS Login Tool. For macOS Catalina and newer, please consider following our guide on using YubiKeys as smart cards with macOS, which can be found here.

Introduction

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 

  1. Download the macOS Login Tool.
  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. Click Close to exit the installation wizard.

Configuration

Configuring Your YubiKeys

To configure the YubiKeys, you will need the YubiKey Manager software. 

  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 the Require touch option 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 strongly recommended that you configure a backup YubiKey so that you are not locked out of your computer if your YubiKey is lost or broken.

Associating Your YubiKeys with Your Account

  1. Open Terminal.
  2. Insert your YubiKey to an available USB port on your Mac.
  3. Run: ykpamcfg -2
    • If you selected the Require touch option, touch the metal contact on your YubiKey when it begins flashing.

Repeat these steps for any additional YubiKeys you wish to associate with your account.

Note: If you receive an error similar to

File /Users/username/.yubico/challenge-7122584 already exists, refusing to overwrite

this 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 -2 command. To do this, for example, if your file is 

/Users/username/.yubico/challenge-7122584

you will want to run the command

rm /Users/username/.yubico/challenge-7122584

to remove it.

Testing the Configuration

Before enabling the two-factor requirement on your Mac, it is important to test that it is working correctly. 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.

First, ensure your Mac is set to require the password immediately after the screensaver starts.

  1. Open System Preferences.
  2. Click Security & Privacy.
  3. Click on the General tab. 
  4. Check the Require password box and set it to 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

  1. 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, insert the YubiKey and confirm you are able to login after entering the correct password.

Enabling the Configuration

Now that you have tested the configuration, you can use the steps below to enable the two-factor requirement at the login screen as well as the screensaver screen.

  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

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

Troubleshooting

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 open a Support Ticket and submit the log.  

Uninstalling the macOS Login Tool

You can use the script in the Uninstalling the macOS Login Tool article to uninstall the tool from your Mac.

Notes

  • Enabling the macOS Login Tool is a system-wide change and will affect all accounts on the Mac. Unlike in Linux, it is not possible in macOS to apply PAM rules to select user accounts. 
  • If Touch ID is enabled, it will bypass the macOS Login Tool due to how Touch ID was implemented.