Yubico PAM module

The Yubico PAM module provides an easy way to integrate the Yubikey
into your existing user authentication infrastructure. PAM is used by
GNU/Linux, Solaris and Mac OS X for user authentication, and by other
specialized applications such as NCSA MyProxy.

Status and Roadmap

The module is working for multi-user systems. The primary mode of
operation is by doing online validation using a YubiKey validation
service (such as the YubiCloud, or a private one configured using
the urllist parameter).

In version 2.6, offline validation was also made possible through
the use of HMAC-SHA1 Challenge-Response found in YubiKey 2.2 and
later. This has introduced a dependency of libykpers-1 from the
ykpersonalize package. Pass --without-cr to configure to avoid
this dependency.

The project is licensed under a BSD license. See the file COPYING for
exact wording. For any copyright year range specified as YYYY-ZZZZ in
this package note that the range specifies every single year in that
closed interval.

Building from Git

Skip to the next section if you are using an official packaged
version.

You may check out the sources using Git with the following command:

git clone https://github.com/Yubico/yubico-pam.git

This will create the directory yubico-pam.

Autoconf, automake, asciidoc and libtool must be installed to create a
compilable source tree.

Generate the build system using:

cd yubico-pam
autoreconf --install

Building

You will need to have libykclient
(ykclient.h, libykclient.so) and libpam-dev (security/pam_appl.h, libpam.so)
installed. It in turn requires cURL, which you need to have installed, and
libyubikey.

To indicate the location of the file that holds the
mappings of Yubikey token IDs to user names.

id

Your API Client ID in the Yubico validation server.
If you want to use the default YubiCloud service,
go here.

key

To indicate your client key in base64 format.
The client key is also known as API key, and provides
integrity in the communication between the client (you)
and the validation server.
If you want to get one for use with the default YubiCloud
service, go here.

debug

to enable debug output.

debug_file

filename to write debug to, file must exist and
be a regular file. stdout is default.

alwaysok

to enable all authentication attempts to succeed
(aka presentation mode).

try_first_pass

Before prompting the user for their password, the module
first tries the previous stacked module´s password in case
that satisfies this module as well.

use_first_pass

The argument use_first_pass forces the module to use a previous
stacked modules password and will never prompt the user - if no
password is available or the password is not appropriate, the user
will be denied access.

urllist

List of URL templates to be used. This is set by calling
ykclient_set_url_bases. The list should be in the format :
https://server/wsapi/2.0/verify;https://server/wsapi/2.0/verify

url

This option should not be used, please use the urllist
option instead.
Specify the URL template to use, this is set by calling
yubikey_client_set_url_template, which defaults to:
https://api.yubico.com/wsapi/verify?id=%d&otp=%s
or
https://api.yubico.com/wsapi/2.0/verify?id=%d&otp=%s
depending on your version of yubico-c-client.

capath

specify the path where X509 certificates are stored. This is
required if https or ldaps are used in url and ldap_uri
respectively.

proxy

specify a proxy to connect to the validation server. Valid schemes are
socks4://, socks4a://, socks5:// or socks5h://. Socks5h asks the proxy
to do the dns resolving. If no scheme or port is specified HTTP proxy
port 1080 will be used.

verbose_otp

This argument is used to show the OTP (One-Time Password) when it
is entered, i.e. to enable terminal echo of entered characters.
You are advised to not use this, if you are using two factor
authentication because that will display your password on the
screen.
This requires the service using the PAM module to
display custom fields. This option can not be used with OpenSSH.

specify the dn where the users are stored
(eg: ou=users,dc=domain,dc=com).

user_attr

specify the LDAP attribute used to store user names (eg:cn).

yubi_attr

specify the LDAP attribute used to store the Yubikey ID.

yubi_attr_prefix

specify the prefix of the LDAP attribute’s value, in case
of a generic attribute, used to store several types of IDs.

token_id_length

Length of ID prefixing the OTP (this is 12 if using the
YubiCloud).

mode

Mode of operation. Use "client" for online validation with
a YubiKey validation service such as the YubiCloud, or use
"challenge-response" for offline validation using YubiKeys
with HMAC-SHA-1 Challenge-Response configurations. See the
man-page ykpamcfg(1) for further details on how to configure
offline Challenge-Response validation.

If you are using "debug" you may find it useful to create a
world-writable log file:

touch /var/run/pam-debug.log
chmod go+w /var/run/pam-debug.log

Authorization Mapping Files

A mapping must be made between the YubiKey token ID and the user ID it is
attached to. 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.

Central authorization mapping

Create a /etc/yubikey_mappings, the file must contain a user name and the
Yubikey token ID separated by colons (same format as the passwd file) for
each user you want to allow onto the system using a Yubikey.

Harder way

This requires you to have the pam module enabled with debug turned on. When
prompted for the YubiKey press the button. The pam module will print out debug
information including the OTP and ID of your token to the shell — copy the ID
into your config file and you should be up and going.

Yubico PAM module and SELinux.

Users with SELinux in enforcing mode (the default on Fedora 17+) may experience
login problems with services including those validated via
polkit-agent-helper-1, sshd and login.

This is documented in Red Hat bugzilla
including a work around for ssh (Equivalent files could be created for
other services). Systems in permissive mode will generate AVC warnings but
authentication will succeed.

To determine if you have SELinux enforcing or not run the sestatus command.

Examples

If you want to use the YubiKey to authenticate you on Linux console
logins, add the following to the top of /etc/pam.d/login: