YubiKey/PAM

Many YubiKeys can be configured to provide FIDO/U2F authentication. This can be configured with the pam_u2f.so module in PAM.

Introduction
YubiKeys provide several interfaces which can be used to authentication or encryption. The U2F/FIDO module can be used to provide authentication for both SSH and PAM, and is commonly used with web services.

PAM is used to provide centralized authentication on Linux systems, using pluggable modules. It is typically used as the backend for authentication as well as most local services which require authentication, such as the login manager, screensavers/lockscreens, and privilege escalation tools such as  or. Using PAM control directives, the required authentication factors can be adjusted depending on what type of service is attempting authentication.

When a username and password are used for authentication, PAM typically uses a combination of the and  files to map users to their passwords. In order to use a YubiKey with PAM, a file which maps users to their YubiKeys is needed. This can be a central file such as or a per-user file such as.

Kernel
Support for raw USB HID devices is required in the kernel for the YubiKey to function.

Emerge
PAM, is modular by design, and adding modules is straightforward. is required to use a YubiKey with PAM. This package provides the PAM module as well as tools to assist in the confutation of this module.

plugdev group
When udev is being used, defines rules that change the ownership of the YubiKey or other fido2/U2F compliant device's associated  to be owned by the plugdev group with the 0660 mode. In order for non-root users to access this, which is required to use, users must be added to the plugdev group.

To check the current user's groups, run:

If is not listed, the user can be added to the group by running:

The user needs to log out and log back in for the group membership to take effect.

Mapping user-tokens
In order to authenticate with PAM using, a key token must be mapped to a user - unless the nouserok module argument is specified. By default, these mappings are read from.

Creating user-token mapping (per-user file)
To create a per-user mapping, insert the YubiKey and run to create a u2f key mapping for the current user:

Enter the u2f pin and tap the presence detection pad once it starts blinking.

Mapping additional keys
To map an additional key to the current user, replace the YubiKey with the next one and run:

Touch the YubiKey when it starts blinking.

Creating user-token mapping (central file)
To create a central mapping file, insert the YubiKey and run (replacing  with the appropriate username):

Touch the YubiKey when it starts blinking.

Mapping additional keys
A little more care is needed when mapping an additional key to a user if a central file is used. It is possible to directly concatenate the output of if a second mapping is created right after the first one. Each user is represented by a single line with colon-delimited entries corresponding to a YubiKey:

Manually copy/pasting the output of the following command onto the end of the relevant user's line in the mapping file is recommended in order to maintain its integrity:

Touch the YubiKey when it starts blinking. Repeat for any remaining YubiKeys.

PAM U2F
Global system authentication is configured through. Taking a backup of the current PAM configuration will make it easy to revert changes if needed.

PAM options
While configuring PAM service files in to work with a YubiKey or other U2F compliant device, several options can be used:

Testing PAM with a YubiKey
In order to test that everything works, temporarily configure PAM to use a YubiKey without locking the user out if fails by adding the following line to the top of :

Attempting to log in as a user with a YubiKey mapped should now prompt for it. Providing a correct YubiKey should result in a successful login.

Requiring a YubiKey
To require a YubiKey to authenticate with PAM, replace  with  :

Requiring a password and a YubiKey
To require both a password and a YubiKey to authenticate with PAM, modify the file to include the following:

means PAM will skip over one module if the current one succeeds. In this case it will jump to the module if the correct password is given.

is included here so that users without a mapping configured are able to authenticate as well. Leave this out to require all users to provide both a password and a YubiKey.

Requiring a password or a YubiKey
To require either a password or a YubiKey to authenticate with PAM (but preferring the YubiKey), modify the file to include the following:

is not included here because it would result in successful authentication without prompting for a password from users without a mapping configured.

Requiring a YubiKey for Sudo authentication
By default, contains , this means it will use whatever is in  for authentication. If system-auth has already been configured to use the YubiKey as desired, and the behavior of system-auth and sudo authentication should be identical, no additional changes are required.. If for some reason, it's desirable to only require YubiKey authentication for, but not system-auth, the following configuration can be used:

Troubleshooting
If no user is able to authenticate after completing the above, then a broken PAM configuration is the likely culprit. Even if no active root login is available, the system can still be fixed and authentication mechanisms restored by either live booting or booting into single-user mode.

Fixing PAM through live boot
First, completely power off the machine. Insert the bootable medium and boot from it through the machine's firmware boot menu. There are no universal instructions since this process can vary greatly from machine to machine, so consult the relevant documentation if unfamiliar with how to do this.

Open up a root shell when booted, locate the block device corresponding to your root filesystem, and mount it (making sure to specify any required mount options):

Next, either restore a backup PAM configuration or manually edit to undo any changes. To non-destructively undo changes, comment out the necessary entries by prepending a  and add any new entries if needed.

Once done, commit the changes to disk, unmount your root filesystem, and reboot:

Authentication should be fully restored.

Fixing PAM through single-user mode
To enter single-user mode first reboot the machine. When the GRUB menu appears, press to bring up the menu entry editor. Any edits made in here are temporary and do not edit the on-disk GRUB configuration.

Locate the line which loads the kernel and append  to it. The actual content and number of kernel command line arguments is likely to differ from system to system, but the end result should look similar to the following:

Press to boot using the present command list.

Once the prompt appears, the root filesystem will need to be re-mounted as read/write:

Only specifying  will instruct  to read the entries in  to find the correct block device and to apply the mount options specified therein.

Next, either restore a backup PAM configuration or manually edit to undo any changes. To non-destructively undo changes, comment out the necessary entries by prepending a  and add any new entries if needed.

Once done, commit the changes to disk, re-mount the root filesystem as read-only, and exit:

This will not be a clean exit and the kernel will with the message. This is fine because all the filesystem changes were manually -ed.

Finally, reboot the system. Authentication should be fully restored.

External resources

 * [//www.man7.org/linux/man-pages/man5/pam.conf.5.html pam.conf(5)], the page describing PAM configuration files.
 * , a description of how keys are generated for U2F on YubiKeys.