This post assumes you are using a recent Ubuntu or similar Debian derivative with apt as your package manager. It is also assumed that your Yubikey is in a mode that supports FIDO/U2F. It should do so out of the box, unless you configured it otherwise.
If you have no clue what PAM is, this ancient article may be as good as any to get you started.
For a description of the different supported modes and how to switch to them see this page. Or you could just install
yubikey-personalization instead and read
man ykpersonalize. ;)
This guide is intended for use with your system locally and will NOT work over ssh. I will write a separate guide for that.
sudo apt-get install libpam-u2f
If you are running Ubuntu you may want to prefer the more update version from the official Yubico PPA. In that case add it first.
sudo add-apt-repository ppa:yubico/stable && sudo apt-get update
Don't forget to press enter when prompted to confirm adding the PPA.
Next, insert your Yubikey into a free USB port on your machine. Then create the following directory. If the directory already exists, you may ignore the resultant error.
Next run the following command, the Yubikey should begin flashing, touch the metal contact to confirm the add.
pamu2fcfg > ~/.config/Yubico/u2f_keys
Add additional Yubikey devices as follows:
pamu2fcfg -n >> ~/.config/Yubico/u2f_keys
Now we can use the token in two different ways. As an example we use the sudo command here. But this can be done for login as well. For a longer more in-depth guide you can always refer to the Yubico site directly.
1FA - one factor authentication
IF the Yubikey is present, touching it will suffice instead of a password to authenticate for sudo use. If the key is not present then a password will be required. Note, whether you feel this is secure enough or not is your judgement call. I make no recommendation either way here.
sudo vi /etc/pam.d/sudo
In the file insert the following below the last line starting with "session" and above the first line starting with "@include".
auth sufficient pam_u2f.so
2FA - two factor authentication
In this instance the Yubikey must be present for sudo use to succeed. The system will first ask you for your password. After that the inserted Yubikey will begin flashing. Only after you then touch the key will sudo succeed.
Be careful here, if you lose and don't have a second Yubikey registered you can screw yourself quite a bit and would have to jump through some hoops to get control back. E.g. boot from a live USB stick, mount your machine's file system, edit /etc/pam.d/sudo to comment out or remove the auth rule.
So to achieve the above 2FA implementation:
sudo vi /etc/pam.d/sudo
Then insert the following line below the "@include common-auth" statement:
auth required pam_u2f.so
You may prefer to go with a more sophisticated challenge response setup instead. The official Yubico guide for this is can be found here.
Note though that their guide will configure the key such that no human interaction is required to respond for the challenge, i.e. the key just needs to be plugged in but not touched. The YubiKey Manager CLI (ykman) tool has the option to configure the key to require touching before the challenge response is returned should you so wish. To activate this function add the "-t" flag before the the "-g" flag in section 3 step 3 of their guide. For a full description of the ykman tool see here.