yubico-pam/doc/Yubikey_and_SSH_via_PAM.adoc

== Introduction ==

The purpose of this document is to guide readers through the configuration
steps to use two factor authentication for SSH using Yubikey. This document
assumes that the reader has advanced knowledge and experience in Linux
system administration, particularly for how PAM authentication mechanism is
configured on a Linux platform.

== Prerequisites ==

Successful configuration of the Yubico PAM module to support two factor
authentication requires following prerequisites:

Operating System::
Any Unix operating system which supports PAM
(http://www.kernel.org/pub/linux/libs/pam[Pluggable Authentication Module])

Complier:: http://gcc.gnu.org[GNU GCC complier]

https://developers.yubico.com/yubico-c-client[Yubico Client C library]::
Version 1.5 or later

https://developers.yubico.com/yubico-pam[Yubico PAM Module]:: Version 1.7 or later

== System Requirements ==

This document illustrates the configuration steps for Fedora Core 8
operating system. However, there steps should work on most other Linux
distributions.

The Yubico PAM module for SSH can be downloaded from
https://developers.yubico.com/yubico-pam/releases.html[here].

The Yubico PAM module support two factor authentication for SSH.
The two factor authentication module verifies the user name and password
for the user and the One-Time Password (OTP) generated by Yubikey assigned
to the user.


== Build yubico-c-client and pam_yubico ==

Build instructions for yubico-c-client and pam_yubico are found in their
respective README.


== Configuration ==

=== Configuration for user and YubiKey token ID mapping ===

There are two ways of user and YubiKey token ID mapping. It can be either
done at administrative level or at individual user level.

==== Administrative Level ====

In Administrative level, system administrators hold right to configure the
user and yubikey token ID mapping. Administrators can achieve this by creating
a new file that contains information about the username and the corresponding
IDs of Yubikey(s) assigned.

This file contains user name that is allowed to connect to the system over SSH
and the token id of the Yubikey(s) assigned to that particular user. A user
can be assigned multiple Yubikeys and this multi key mapping is supported by
this file. However, presently there is no logic coded to detect or prevent use
of same Yubikey ID for multiple users.

Each record in the file should begin on a new line. The parameters in each
record are separated by `:` character similar to `/etc/passwd`. 

The contents of this file are as follows:

 <user name>:<yubikey token ID>:<yubikey token ID>: ….

 <user name>:<yubikey token ID>:<yubikey token ID>:…..

e.g.

--------
paul:indvnvlcbdre:ldvglinuddek
simon:uturrufnjder:hjturefjtehv
kurt:ertbhunjimko
--------

The mapping file must be created/updated manually before configuration of
Yubico PAM module for SSH authentication.

===== Configuration of modified pam_yubico.so module at administrative level =====

Append the following line to the beginning of the `/etc/pam.d/sshd` file:

 auth required pam_yubico.so id=16 debug authfile=/path/to/mapping/file

Make sure you set `id=16` to the correct API-id for the yubico validation server.

After the above configuration changes, whenever a user connects to the server
using any ssh client, the PAM authentication interface will pass the control to
Yubico PAM module. The Yubico PAM module first checks the presence of authfile
argument in PAM configuration.  If authfile argument is present, it parses the
corresponding mapping file and  verifies the username with corresponding
Yubikey token id as configured in the mapping file. If valid, the Yubico PAM
module extracts the OTP string and sends it to the Yubico authentication server
or else it reports failure.  If authfile argument is present but the mapping
file is not present at the provided path PAM module reports failure. After
successful verification of OTP Yubico PAM module from the Yubico
authentication server, a success code is returned.


==== User Level ====

In User level, individual users have the ability to configure yubikey token
ID assigned to them. Users can achieve this by creating a new file
`.yubico/authorized_yubikeys` inside their home directories that contains
information about the username and the corresponding IDs of Yubikey(s) assigned
to them. A user can be assigned multiple Yubikeys and the multi key mapping is
supported by this file.

This file must contain only one record. The parameters in the record are
separated by `:` character similar to `/etc/passwd`. The contents of this file
are as shown below:
 
 <user name>:<yubikey token ID>:<yubikey token ID>: ….

e.g.

 paul:indvnvlcbdre:ldvglinuddek


The `.yubico/authorized_yubikeys` file must be created/updated manually and must
be placed inside user's home directory before configuration of Yubico PAM
module for SSH authentication.


===== Configuration of modified pam_yubico.so module at user level =====

Append the following line to the beginning of the `/etc/pam.d/sshd` file:

 auth required pam_yubico.so id=16 debug

After the above configuration changes, whenever a user connects to the server
using any SSH client, the PAM authentication interface will pass the control
to Yubico PAM module. The Yubico PAM module first verifies the username with
corresponding Yubikey token id as configured in the `.yubico/authorized_yubikeys`
file that present in the user's home directory who is trying to assess server
through SSH. If valid, the Yubico PAM module extracts the OTP string and sends
it to the Yubico authentication server or else it reports failure. After
successful verification of OTP Yubico PAM module from the Yubico authentication
server, a success code is returned.


=== pam_unix.so configuration ===

Append _try_first_pass_ parameter to the _pam_unix.so_ module to authenticate
the user with password passed from the preceding auth module. 

The _pam_unix.so_ module used for authentication is generally located into
`/etc/pam.d/system-auth` for RedHat based Linux system and into
`/etc/pam.d/common-auth` for Debian based Linux systems.

=== SSH configuration ===

Edit the sshd configuration file `/etc/ssh/sshd_config`_ to disable challenge-
response passwords. Change `challenge-response passwords yes` to
`challenge-response passwords no`.


== Test Setup ==

=== Fedora 8 ===

Test setup for fedora 8 environment is as follows:

OS Version:: Fedora release 8 (Werewolf)
Kernel Version:: Kernel version 2.6.23.1-42.fc8
OpenSSH Version:: openssh-4.7p1-2.fc8
Yubico PAM Version:: pam_yubico-1.7

=== Fedora 6 ===

Test setup for fedora 6 environment is as follows:

OS Version:: Fedora Core release 6 (Zod)
Kernel Version:: Kernel version 2.6.18-1.2798.fc6
OpenSSH Version:: openssh-4.3p2-10
Yubico PAM Version:: pam_yubico-1.7


=== PAM configuration ===

PAM configuration files in our testing environment are as follows:


==== /etc/pam.d/sshd ====
-------
auth           required  	 pam_yubico.so authfile=/etc/yubikeyid id=16 debug
auth           include   	 system-auth
account        required  	 pam_nologin.so
account        include   	 system-auth
password       include   	 system-auth
session        optional  	 pam_keyinit.so force revoke
session        include   	 system-auth
session        required  	 pam_loginuid.so
-------


==== /etc/yubikeyid ====

-------
root:indvnvlcbdre:ldvglinuddek
test:ldvglinuddek
-------

===== /root/.yubico/authorized_yubikeys =====

-------
root:indvnvlcbdre:ldvglinuddek
-------

Please change PAM configuration settings for SSH as shown above and test the
configuration. 


== Testing the Configuration ==

We assume that you have 'root' and 'test' user configured to access SSH on your
test environment with password 'secret' and 'pencil' respectively. 
 
Use any standard SSH client for testing (We used SSH command line utility).   

Try to login to server with SSH client as configured user:

------
$ ssh -l test localhost 
Password: (enter 'pencil' and touch the ldvglinuddek yubikey)
------

------
$ ssh -l root localhost
Password: (enter 'secret' and touch the ldvglinuddek yubikey)
------

------
$ ssh -l root localhost
Password: (enter 'secret' and touch the indvnvlcbdre yubikey)
------