YubiKey/PAM

This page goes over Article description::authenticating with PAM using a YubiKey.

Emerge
The main component is a PAM module called pam-u2f. The package also contains a tool called pamu2fcfg which is used to generate the required authorization mappings.

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

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

If plugdev 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.

Creating an authorization mapping
In order to authenticate with PAM using pam-u2f, a key token needs to be mapped to a user. By default, these mappings are stored in ~/.config/Yubico/u2f_keys. To create a mapping, insert the YubiKey and run:

Touch the YubiKey when it starts blinking.

Mapping additional keys
To map additional keys to a user, remove the currently inserted YubiKey (if any) and insert the next one. Then run:

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

Configuring PAM
Global system authentication is configured through /etc/pam.d/system-auth.

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

success=1 means PAM will skip over one module if the current one succeeds. In this case it will jump to the pam-u2f module if the correct password is given. nouserok means the pam-u2f 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. cue means the user is prompted to touch the YubiKey during authentication. Without this, no prompt is given.

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

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

External resources

 * (Link to external resources [outside the Wiki] using bullet points in this section. It is common for the information in this section to be full sentences that are links.)