Using a YubiKey for authentication at a Fedora Linux Workstation

Let me tell you how to configure a YubiKey 5C NFC and Linux PAM to authenticate in all cases PAM is used and you’d like to use a YubiKey. This post will cover not only authentication to GDM but also in a terminal or when using sudo. All of these features use the Linux Pluggable Authentication Modules (PAM) system and are configured in the same way. After a base setup of the YubiKey and PAM it’ll be easy to make the key a second- or an alternative factor.

If you ask yourself “What is a YubiKey?”, “Where do I buy one?” or “What features does a YubiKey offer?” I invite you to read my introductory post on the matter.

Configure a backup key - No kidding

As these hardware tokens are unique by design it is pretty easy to lock yourself out of everything should you loose the key in any way. I can’t stress on this fact enough. Therefore I always have a second key ready for registration to services or generating private keys which is always kept somewhere safe.

Always test the configuration in a second session

Especially login and sudo are features where you have great potential of locking yourself out of the system or at least of administration commands. Make sure to keep a sudo authenticated session open at all times and test each feature in a separate session.

YubiKey OTP

The feature used for this is OTP - One Time Password. There are two slots for OTP credentials and operation modes on the key. Each YubiKey comes pre-configured with a YubiCloud credential in slot 1 and a free slot 2. The YubiCloud credential is ready to use although it is recommended to register the key to obtain an API key if online authentication against the Yubico servers is desired. Alternatively the second slot can be configured with a challenge-response secret which allows offline authentication.

Pre-requisites

You’ll need two packages from the official Fedora repositories: pam_yubico and yubikey-manager.

sudo dnf install -y pam_yubico yubikey-manager

Registration of the Key

If you use the online YubiCloud method you need the ID of your YubiKey. For this just enter the key and retrieve an OTP code with a short press on the button and extract the first 12 characters – this is your key ID:

cccccbcgebif | bclbtjihhbfbduejkuhgvhkehnicrfdj

Next create a configuration file in ~/.yubico/authorized_yubikeys and add all authorized key IDs after your username separated by colons:

w4tsn:cccccbcgebif[:<another-key-id>]

If you go for the offline challenge-response method you need at least one slot configured for challenge-response. Let’s assume Slot 1 is used in it’s default configuration with YubiCloud OTP for other things so configure the 2nd slot for challenge-response:

ykman otp chalresp --generate --touch 2

Now register a connected YubiKey with your user account via challenge-response:

ykpamcfg -2

This creates a file in ~/.yubico/challenge-<key-serial> that contains a challenge response configuration for the key.

Base PAM configuration

Create two base configuration files using the pam_yubico module. One which instructs PAM to consider the YubiKey an alternative factor and one so PAM requires the key as an additional factor.

For the online YubiCloud method use:

/etc/pam.d/yubikey-required
#%PAM-1.0
auth       required     pam_yubico.so id=[Your API Client ID] key=[Your API Client Key]

/etc/pam.d/yubikey-sufficient
#%PAM-1.0
auth       sufficient     pam_yubico.so id=[Your API Client ID] key=[Your API Client Key]

You need to register your YubiKey at YubiCloud and obtain an API key as said before. The module will work without an API key but then the client will not verify OpenSSL certificates and be susceptible to MitM-Attacks.

For offline challenge-response use:

/etc/pam.d/yubikey-required
#%PAM-1.0
auth       required     pam_yubico.so mode=challenge-response

/etc/pam.d/yubikey-sufficient
#%PAM-1.0
auth       sufficient     pam_yubico.so mode=challenge-response

Choosing modules and including the YubiKey config

Now choose the PAM modules to consider the YubiKey and then include the respective configuration file, either before or after the system-auth import depending on whether sufficient or required is what you want:

• /etc/pam.d/login – For console logins
• /etc/pam.d/sudo – For sudo authentication
• /etc/pam.d/gdm-password – For GNOME authentication
• /etc/pam.d/sshd – SSH authentication against a local OpenSSH Server

For YubiKey as additional / required factor:

auth include system-auth
...
auth include yubikey-required

For YubiKey as alternative / sufficient factor:

auth include yubikey-sufficient
...
auth include system-auth

Note: if you add the YubiKey as a factor in sudo authentication make sure to have a root shell open and test it thoroughly in another shell. Otherwise you could loose the ability to use sudo.