Complete U2F Yubikey Linux Mint 20 Login with Encrypted Home Folders

Updated on 2021-05-26


This tutorial was created and tested on Linux Mint 20.1.

Tutorial assumes you have a U2F capable Yubikey on hand.

Instructions here should work very similarly on other distributions like Ubuntu or Debian…

The first main consideration when setting up U2F is your chosen Window Manager that your distribution ships with, or you have installed / setup.

This tutorial uses LightDM window manager, as that is what Linux Mint 20 ships with.

The second consideration is an encrypted home folder. If you use an encrypted home folder with eCryptFS, then your authentication key file data needs to be stored somewhere outside of your
personal non-root user home folder. Otherwise you will not be able to login after you logout or reboot your system!

This tutorial covers the above scenarios completely.

Please be aware there are several tutorials available online, and especially on Youtube, that will instruct you to associate your Yubikeys with a online web service such as YubiCloud, etc.

Even the current APT package description for libpam-yubico is semi mis-leading in my opinion.
Implying that a online service is required to use the library or product.

No online service, or provider is needed for Yubikey U2F login to a Linux system.

You do not need a functioning Internet connection for login.

While I am sure there are some situations where validating against an online service is nice or ideal, I personally would consider any guide which instructs you to connect to an online service just for Linux Login to be invalid or severely out-of-date in 2021.

Goals for this Tutorial

In this tutorial we want to use a Yubikey USB hardware token as a U2F device to enable login to the system and for usage with sudo.


  • A password AND a Yubikey will be needed to login. (This is U2F). Something you know, and something you have possession of.

  • However, if you do not have one of the Yubikeys associated with the system, you will be unable to login without making changes to your system from a rescue media boot disk.

To clarify, this will not be “passwordless” login where only the Yubikey is needed to login.

NOTE: If you want “passwordless” login, please look for Yubikey login “Challenge Response” login tutorial in the Reference section at the bottom of this page.
(challenge response is not actually “passwordless”, but a static password so long, it is not practical to type out manually.)

For the purpose of this guide, we will only configure the system with one (1) Yubikey, but it is recommended to add at least two (2) Yubikey style U2F devices, or some other U2F style option such as an Authenticator application to the PAM settings.

A good setup could include, 2 Yubikeys, 1 Solo Key, 1 Ledger Nano with U2F, and 1 Authenticator App on a mobile phone OS as a last resort.

NOTE: Feel free to change the directory names and file names as you please, but for this guide it is recommended to use the names as outlined below.

Main Considerations for U2F login on Linux Systems

  1. Graphical Window Manager Login Window (fresh boot, etc.)
  2. Screensaver / Lock Screen login window (current session)
  3. TTY Logins on virtual terminals. (typically tty1 - tty6)
  4. sudo access to elevate to root user privileges.

Sample Yubikey product outlines

Install required package(s) via apt or aptitude

apt update ; apt install debug libpam-u2f libpam-yubico libyubikey-udev libyubikey0


It seems that libpam-u2f might be the only package above really needed for the basics to function. But I have installed extra packages for additional testing scenarios. YMMV.

Prepare the Yubikey for regular user account

  • Login as a normal non-root user.

  • Open Terminal.

  • Insert your U2F capable Yubikey into USB port now.

  • Run: mkdir -p ~/.config/yubico

  • Run: pamu2fcfg >> ~/.config/yubico/u2f_keys

  • When your device begins flashing, touch the metal contact to confirm the association.

  • Repeat this process above for each Yubikey USB device / User Account Pair you want to associate with this Linux System for U2F login.

  • NOTE: Once U2F is enabled as defined in this tutorial, no user accounts will be able to login, UNLESS, they have configured U2F on their user account.

Copy u2f_keys files to /etc/yubico directory

For proper screen saver and login window access you must move the key file to somewhere that root user can read each users Yubikey key file data after a fresh system boot.

If you only keep it on a encrypted Home Folder partition, root user will not be able to see this file after a reboot.

  • Run: mkdir -p /etc/yubico

  • Run: sudo cp $HOME/yubico/u2f_keys /etc/yubico

  • Run: sudo chmod 644 /etc/yubico/u2f_keys

NOTE: It is important that this file copied to /etc/yubico is readable by other users, otherwise things WILL BREAK.

Most notable thing that will break is Cinnamon Screensaver, if the keys file is only readable by the root user.

It is probably safe to remove / delete the .config/yubico directory from your home folder now. But I have chosen to leave it in my encrypted home directory.

Important note about root user login

  • If you want to be able to login as root user directly, YOU MUST run pamu2fcfg utility for the root user.

The data must be stored in /etc/yubico/u2f_keys or any other root user accessible location.

Otherwise you will NOT be able to login as root user directly.

Snippet exmaple of /etc/yubico/u2f_keys file

Each user account should be on a line of it’s own.


Become root user before making the these edits

It is important to have a full root shell for the following procedure and do not use sudo.

You should have one root shell on at least one TTY virtual terminal. (e.g. tty1)

  • press Ctrl-Alt-1 to switch to tty1.

  • And one root shell graphical terminal on tty7.

If you make mistakes with these instructions and have no active root login shells active, you will be locked out of your system completely and may or may not be able to rescue your system with live media boot disk.

sudo su - root

Complete list of files that need to be modified

  • /etc/pam.d/cinnamon-screensaver
  • /etc/pam.d/login
  • /etc/pam.d/lightdm
  • /etc/pam.d/sudo

General process for editing all files

We will need to add our Yubikey configuration to below the line that has:

@include common-auth


Should look roughly like this with new line immediately below @include common-auth

@include common-auth
auth    required      authfile=/etc/yubico/u2f_keys
auth optional

Test Screen lock now

After you have made a change to the above file, you can test locking your screen. Look to see that your Yubikey device lights up 1 or 2 LED’s after you enter your password.

If you can get back into your graphical login after testing this, proceed with the next steps below.


Add tab separated line that looks like this below @include common-auth

auth    required      authfile=/etc/yubico/u2f_keys


Add tab separated single line below @include common-auth

auth    required      authfile=/etc/yubico/u2f_keys


One beauty of Unix-based systems is the extreme custom configuration options one can have.

It is not strictly required to use U2F for a purpose like sudo, but it does really help to secure a system beyond just the login window and screensaver.

If you have configured the file /etc/sudoers to not require a password, then this tutorial here will simply just require you to touch the metal contact on the side of the Yubikey to execute sudo commands.

To configure sudo command to use your Yubikey device, add the following line to /etc/pam.d/sudo.

Add a single line below @include common-auth

auth    required      authfile=/etc/yubico/u2f_keys

Test sudo with U2F in a graphical terminal

  • Keep all your existing root logins open

  • Open a new Terminal window

  • Run something simple like sudo whoami

  • Enter password when/if prompted.

  • You should be prompted by Yubikey to touch the metal contact on the side.

sudo command should complete

You can also unplug your Yubikey and run the same test.

It should fail every time with no Yubikey present even if you enter your password correctly.

Logout of the graphical session and log back in

You need to test logging out of the graphical session now on tty7 now.

The root login on tty1 will still be logged in and let you fix errors in case you made an error and broke the login window.

Reboot System ; Test Login

By now you have tested the screensaver with U2F.
Also you tested the sudo command.

If sudo works and you were able to successfully log out and log in to the graphical session again as noted above…
You need to test a full reboot of the entire system.

If you configured everything correctly, you should be able to login to a graphical session with your Yubikey plugged in after a reboot.
Login should fail if it is not plugged in or you do not press the metal contact button after a few seconds.

During login you should also be prompted for Yubikey U2F on any tty after a reboot.
Including the Graphical login with your Window Manager.

Congratulations for configuring your system with hardware based U2F!

Appendix - Further Yubikey(s) Options + Customization

If you want to set or modify additional settings on your yubikey, for challenge response, etc.
The following command line application and GUI appliction may be helpful:

aptitude install yubikey-personalization yubikey-personalization-gui

Appendix - Yubico Authenticator

flatpak install -y com.yubico.yubioath
  • This is cross-platform application / process superior to the poorly implemented tech like “Google Authenticator”.

  • …But still not as ideal as proper U2F WebAuthN token support.

  • Still it is really handy for dealing with older web systems that only support SHA1 style “Authenticator Application” that are literally stuck on a single device.