macOS Logon Tool Configuration Guide

Applicable Products


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 Logon 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.

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 Logon Tool after following this guide, the 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 Logon 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.
  • If Touch ID is enabled, it will bypass the macOS Logon Tool due to how Touch ID was implemented. 

Did you find it helpful? Yes No

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