Ubuntu Linux Login Guide - U2F

Applicable Products


1 Introduction

This guide covers how to secure a local Linux login using the U2F feature on YubiKeys and Security Keys. This does not work with remote logins via SSH or other methods. The commands in the guide are for an Ubuntu (or Ubuntu based) system, but the instructions can be adapted for any distribution of Linux.

2 Installing the Required Software

  1. If you haven’t already, Enable the Yubico PPA.
  2. Open Terminal.
  3. Run: sudo apt-get install libpam-u2f

3 Associating the U2F Key(s) With Your Account

  1. Open Terminal.
  2. Insert your U2F Key.
  3. Run: mkdir ~/.config/Yubico
    • If you receive an error that this folder exists, you can ignore it and proceed to the next step.
  4. Run: pamu2fcfg > ~/.config/Yubico/u2f_keys
  5. When your device begins flashing, touch the metal contact to confirm the association.

If you have backup devices, use the steps below to associate them with your account. If you do not have a backup device available at this time, you can add one later using the steps below as long as you still have access to your account. Warning: Having a backup device is strongly recommended so that if your device is lost or broken, you will not be locked out of your computer.

  1. Open Terminal.
  2. Run: pamu2fcfg -n >> ~/.config/Yubico/u2f_keys
  3. When your device begins flashing, touch the metal contact to confirm the association.

4 Configuring the System to Use the U2F Keys

4.1 Test Configuration with the Sudo Command

This section covers how to require the YubiKey when using the sudo command, which should be used as a test so that you do not lock yourself out of your computer.

  1. Open Terminal.
  2. Run: sudo nano /etc/pam.d/sudo
  3. Add the line below after the “@include common-auth” line.

auth       required   pam_u2f.so

  1. Press Ctrl+O and then Enter to save the file. Be sure you do not close the Terminal window, otherwise you will not be able to revert the changes.
  2. Remove your device from the computer.
  3. Open a new Terminal
  4. In the new Terminal, run: sudo echo test. When prompted, enter your password and press Enter
    1. Even with the correct password, the authentication should fail as the U2F Key is not plugged in. If the authentication succeeds without the U2F Key, that indicates the U2F PAM module was not installed or there is a typo in the changes you made to /etc/pam.d/sudo. 
  5. Insert your device.
  6. Open a new Terminal and run sudo echo test again. When prompted, enter your password and press Enter. Then, touch the metal contact on your U2F Key when it begins flashing.

Congrats! If the password was accepted this time you have configured the system correctly and can continue on to the next section for requiring the U2F Key to login. Note: if you do not want to require the U2F Key to run the sudo command, remove the line you added to the /etc/pam.d/sudo file.

4.2 Configuring the System to Require the YubiKey for Login

  1. Open Terminal.
  2. If your system is Ubuntu 17.10 or newer, run: sudo nano /etc/pam.d/gdm-password. If your system is Ubuntu 17.04 or older, run: sudo nano /etc/pam.d/lightdm
  3. Add the line below after the “@include common-auth” line.

auth       required   pam_u2f.so

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

Success! You will no longer be able to log in to the computer without the U2F device.

5 Alternate Configurations

5.1 Login with the U2F Key Only (1FA)

If you would prefer to not require a password for login or running sudo, you can use auth sufficient instead of auth required in the respective configuration files.

6 Troubleshooting

6.1 Enabling Debug Mode

If you are unable to login and are unsure why, you can enable debugging on the Yubico PAM module using the steps below. This provides insight into why the module is not allowing the login.

  1. Open Terminal.
  2. Run: sudo touch /var/log/pam_u2f.log
  3. If your system is Ubuntu 17.10 or newer, run: sudo nano /etc/pam.d/gdm-password. If your system is Ubuntu 17.04 or older, run: sudo nano /etc/pam.d/lightdm
  4. Add “ debug debug_file=/var/log/pam_u2f.log” to the end of the line that contains pam_u2f.so

Each subsequent login event will have the debug log saved in the /var/log/pam_u2f.log file.

Did you find it helpful? Yes No

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