= Pluggable Authentication Module (PAM) Universal 2nd Factor (U2F)
image:https://github.com/yubico/pam-u2f/workflows/linux/badge.svg["Linux Build Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"] image:https://github.com/yubico/pam-u2f/workflows/macos/badge.svg["macOS Build Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"] image:https://github.com/yubico/pam-u2f/workflows/fuzzer/badge.svg["Fuzz Status (github actions)", link="https://github.com/Yubico/pam-u2f/actions"]
This module implements PAM over U2F and FIDO2, providing an easy way to integrate the YubiKey (or other U2F/FIDO2 compliant authenticators) into your existing infrastructure.
[[building]] == Building
You may get signed release tarballs from Yubico's https://developers.yubico.com/pam-u2f/Releases[release page].
This project uses 'autoconf', 'automake', 'pkg-config' and 'libtool' to achieve portability and ease of use.
In addition, https://developers.yubico.com/libfido2['libfido2'] (>=
1.3.0) is needed. Versions of this project up to 1.0.8 used
libu2f-host
and libu2f-server
. On Ubuntu, the necessary dependencies can be
installed using
libfido2-dev libpam-dev libssl-dev
If you downloaded a tarball, build it as follows.
== Building from Git
You may check out the sources using Git with the following command:
This will create a directory 'pam-u2f'. Enter the directory:
autoconf
, automake
, libtool
, and libpam
must be installed.
AsciiDoc
and xsltproc
are used to generate the manpages. On Ubuntu,
the necessary dependencies can be installed using
pkg-config libfido2-dev libpam-dev libssl-dev asciidoc xsltproc \
libxml2-utils docbook-xml
On Fedora, the necessary dependencies can be installed using
openssl-devel asciidoc
Generate the build system using:
Then build as usual, see above under <<building,Building>>.
== Installation
Once the module is built, copy the file pam_u2f.so
to the correct
directory for your system. Typically /lib/security/
or
/lib/x86_64-linux-gnu/security/
. This is automated by make install
assuming that the pam directory chosen by configure
is correct. If
that is not the case it can be specified with ./configure --with-pam-dir=
.
== Service Configuration
Create a file for a new service in /etc/pam.d/
or edit an already
existing one by adding a line similar to this:
For more information about the syntax of PAM configuration files, please see the manual page for pam.conf(5). Additional <<examples,example configurations>> can be found below.
IMPORTANT: An erroneous PAM configuration may lock some or all users out of the system or prevent you from gaining root privileges. It is recommended that you start a separate shell with root privileges while configuring PAM to be able to revert changes if something goes wrong. Test your configuration thoroughly before closing the root shell.
=== Module Arguments
[horizontal] debug:: Enables debug output
debug_file:: Filename to write debugging messages to. If this file is missing, nothing will be logged. This regular file has to be created by the user or must exist and be a regular file for anything getting logged to it. It is not created by pam-u2f on purpose (for security considerations). This filename may be alternatively set to "stderr" (default), "stdout", or "syslog".
origin=origin:: Set the relying party ID for the FIDO authentication procedure. If no value is specified, the identifier "pam://$HOSTNAME" is used.
appid=appid:: Set the https://developers.yubico.com/U2F/App_ID.html[application ID] for the FIDO authentication procedure. If no value is specified, the same value used for origin is taken ("pam://$HOSTNAME" if also origin is not specified). This setting is only applicable for U2F credentials created with pamu2fcfg versions v1.0.8 or earlier. Note that on v1.1.0 and v1.1.1 of pam-u2f, handling of this setting was temporarily broken if the value was not the same as the value of origin.
authfile=file:: Set the location of the <<authMappingFiles,file that holds the mappings of user names to keyHandles and user keys>>. An <<individualAuth,individual (per user) file>> may be configured relative to the users' home dirs, e.g. ".ssh/u2f_keys". If not specified, the location defaults to $XDG_CONFIG_HOME/Yubico/u2f_keys. If $XDG_CONFIG_HOME is not set, $HOME/.config/Yubico/u2f_keys is used.
expand::
Enables variable expansion within the authfile path: %u
is expanded to the
local user name (PAM_USER
) and %%
is expanded to %
. Unknown expansion
sequences result in an authentication error. See also openasuser
.
authpending_file=file::
Set the location of the file that is used for touch request
notifications. This file will be opened when pam-u2f starts waiting
for a user to touch the device, and will be closed when it no longer
waits for a touch. Use inotify to listen on these events, or a more
high-level tool like
https://github.com/maximbaz/yubikey-touch-detector[yubikey-touch-detector].
Note that yubikey-touch-detector v1.5.1 and later no longer rely on the
authpending file for its detection mechanism. Set an empty value in order to
disable this functionality, like so: authpending_file=
. Default value:
/var/run/user/$UID/pam-u2f-authpending
nouserok::
Set to enable authentication attempts to succeed even if the user
trying to authenticate is not found inside authfile
or if authfile
is missing/malformed.
openasuser::
Setuid to the authenticating user when opening the authfile. Useful
when the user's home is stored on an NFS volume mounted with the
root_squash
option (which maps root to nobody which will not be able
to read the file). Note that after release 1.0.8 this is done by
default when no global authfile (path is absolute) or XDG_CONFIG_HOME
environment variable has been set.
alwaysok:: Set to enable all authentication attempts to succeed (aka presentation mode).
max_devices=n_devices:: Maximum number of devices (credentials) allowed per user (default is 24). Devices specified in the authorization mapping file that exceed this value will be ignored.
interactive:: Set to prompt a message and wait before testing the presence of a FIDO device. Recommended if your device doesn't have a tactile trigger.
Set individual prompt message for interactive mode. Watch the square brackets around this parameter to get spaces correctly recognized by PAM.
manual:: Set to drop to a manual console where challenges are printed on screen and response read from standard input. Useful for debugging and SSH sessions without U2F-support from the SSH client/server. If enabled, interactive mode becomes redundant and has no effect.
cue:: Set to prompt a message to remind to touch the device.
Set individual prompt message for the cue option. Watch the square brackets around this parameter to get spaces correctly recognized by PAM.
nodetect::
Set to skip detecting if a suitable FIDO token is inserted before
performing the full tactile authentication. This detection was created
to avoid emitting the "cue" message if no suitable token exists,
because doing so leaks information about the authentication stack if a
token is inserted but not configured for the authenticating user.
However, it was found that versions of libu2f-host
1.1.5 or less has
buggy iteration/sleep behavior which causes a 1-second delay to occur
for this initial detection. For this reason, as well as the
possibility of hypothetical tokens that do not tolerate this double
authentication, the "nodetect" option was added.
userpresence=int:: If 1, request user presence during authentication. If 0, do not request user presence during authentication. If omitted, fallback to the authenticator's default behaviour.
userverification=int:: If 1, request user verification during authentication (e.g. biometrics). If 0, do not request user verification during authentication. If omitted, fallback to the authenticator's default behaviour. If enabled, an authenticator with support for FIDO2 user verification is required.
pinverification=int:: If 1, request PIN verification during authentication. If 0, do not request PIN verification during authentication. If omitted, fallback to the authenticator's default behaviour. If enabled, an authenticator with support for a FIDO2 PIN is required.
sshformat:: Use credentials produced by versions of OpenSSH that have support for FIDO devices. It is not possible to mix native credentials and SSH credentials. Once this option is enabled all credentials will be parsed as SSH.
IMPORTANT: On dynamic networks (e.g. where hostnames are set by DHCP), users should not rely on the default origin and appid ("pam://$HOSTNAME") but set those parameters explicitly to the same value.
[[examples]] === Example Service Configurations
==== Second Factor Authentication
Configure pam-u2f as a required
module after your primary authentication
module(s) for use as a second factor. Make sure that the primary authentication
method is not sufficient
or uses other control values that may preempt
execution of pam-u2f.
==== Passwordless Authentication
For a passwordless experience, where the authenticator PIN can be used in place of the user password, you can insert the below line towards the top of your service configuration. You may need to change the control value to something else if you'd like to execute additional authentication modules after pam-u2f.
auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1
==== Passwordless Authentication using Biometrics
Similar to the previous configuration but capable of built-in user verification, e.g. fingerprint matching using the YubiKey Bio. This example falls back to using PIN verification if the fingerprint does not match or is otherwise blocked.
auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=0 userverification=1 auth sufficient pam_u2f.so authfile=/etc/u2f_mappings cue pinverification=1 userverification=0
[[authMappingFiles]] == Authorization Mapping Files
A mapping must be made between the YubiKey token and the user name, see <<registration, here>> for details on how to perform the registration using the bundled tool.
There are two ways to do this, either centrally in one file, or individually, where users can create the mapping in their home directories. If the central authorization mapping file is being used, user home directory mappings will not be used and the opposite applies if user home directory mappings are being used, the central authorization mappings file will not be used.
By default the mapping file inside a home directory will be opened as
the target user, whereas the central file will be opened as root
. If
the XDG_CONFIG_HOME
variable is set, privileges will not be dropped
unless the openasuser
configuration setting is set.
IMPORTANT: Using pam-u2f to secure the login to a computer while storing the mapping file in an encrypted home directory, will result in the impossibility of logging into the system. The partition is decrypted after login and the mapping file can not be accessed.
=== Central Authorization Mapping
Create a file e.g. /etc/u2f_mappings
. The file must contain a user
name, and the information obtained during the registration procedure.
The mappings should look like this, one per line: