mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-12-01 15:24:12 +01:00
244 lines
8.1 KiB
Plaintext
244 lines
8.1 KiB
Plaintext
== 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)
|
|
------
|