YubiKey/PAM

This page describes Article description::how to setup a YubiKey for authenticating with [[PAM.]]

Introduction
PAM is the central authentication service that is used when you log in to a TTY shell, but also your login manager, screensaver-application or SSH daemon. In PAM, it can be configured to use YubiKeys as a complement to username/password, or as a replacement.

When username/password is used for authentication, PAM uses the /etc/shadow file to map users to passwords. To make it possible to use YubiKeys as complement to username/password, a similar-but-different file is needed to map users to YubiKeys. This can be one central file, such as /etc/u2f_mappings, or a file per user, such as ~/.config/Yubico/u2f_keys.

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

Emerge
PAM has a pluggable architecture. To make the YubiKey work, we will mainly use the component. This component will also interact with the mapping file(s) that stores which user should be authenticated when a given YubiKey is used to login.

The package also contains a tool called which is used to generate the required mappings.

plugdev
For a non-root user to be able to access the YubiKey, they need to be a member of the group. To check if the current user is in the group, run:

If is not listed, add the user to the group by running:

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

Configuration
In order to authenticate with PAM using, a key token needs to be mapped to a user. By default, these mappings are stored in. Alternatively, a central mapping file such as can be configured.

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

Touch the YubiKey when 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 file (central file)
To create a central mapping file, insert the YubiKey and run (replace joeuser with appropriate username):

Touch the YubiKey when it starts blinking.

Mapping additional keys
To map an additional key to the current user, we need to be a little more careful than with separate files. If done straight after creating the file it is possible to replace the YubiKey and directly concatenate output. However, in the file each user is represented by a single line with colons to separate YubiKeys:

Therefore, we prefer that you manually copy and paste the string in the mappings file:

(Again, touch the YubiKey when it starts blinking.) Then copy the contents and paste it into /etc/u2f_mappings

Repeat for any remaining YubiKeys.

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

Requiring a password and YubiKey (per-user mappings file)
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. means the module will succeed if the authenticating user doesn't have an authorization mapping. Without this, any users that don't have a mapping configured will be locked out. means the user is prompted to touch the YubiKey during authentication. Without this, no prompt is given.

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

means PAM will consider the authentication to be successful if this module succeeds. Otherwise it goes to the next module. is not included because otherwise will succeed for users without a mapping configured. This would result in successful authentication without prompting for a password.

Requiring a password and YubiKey (central mappings file)
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. means the module will succeed if the authenticating user doesn't have an authorization mapping. Without this, any users that don't have a mapping configured will be locked out. means the user is prompted to touch the YubiKey during authentication. Without this, no prompt is given.

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

means PAM will consider the authentication to be successful if this module succeeds. Otherwise it goes to the next module. is not included because otherwise will succeed for users without a mapping configured. This would result in successful authentication without prompting for a password.

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.

Supported devices
The following tables list all the YubiKey devices and their U2F support as stated on the Yubico website.

External resources

 * [//www.man7.org/linux/man-pages/man5/pam.conf.5.html pam.conf(5)], the page describing PAM configuration files.