mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-12-01 15:24:12 +01:00
276 lines
8.7 KiB
Plaintext
276 lines
8.7 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.
|
|
|
|
Details
|
|
-------
|
|
|
|
|
|
Prerequisites
|
|
-------------
|
|
|
|
Successful configuration of the Yubico PAM module to support two factor
|
|
authentication requires following prerequisites:
|
|
|
|
1) Operating System: Any Unix operating system which supports PAM
|
|
(Pluggable Authentication Module)
|
|
(http://www.kernel.org/pub/linux/libs/pam/)
|
|
|
|
2) Complier : GNU GCC complier (http://gcc.gnu.org/)
|
|
|
|
3) Yubico Client C library version 1.5 or later
|
|
(https://developers.yubico.com/yubico-c-client/)
|
|
|
|
4) Yubico PAM Module: Yubico PAM Module Version 1.7 or later
|
|
(https://developers.yubico.com/yubico-pam/)
|
|
|
|
|
|
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
|
|
|
|
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 are found in the README:
|
|
|
|
https://github.com/Yubico/yubico-c-client/wiki/ReadMe
|
|
|
|
Build instructions for pam_yubico are found in the README:
|
|
|
|
https://github.com/Yubico/yubico-pam/wiki/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.
|
|
|
|
1) 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 /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.
|
|
|
|
|
|
2) 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 /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.
|
|
|
|
|
|
3) 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.
|
|
|
|
4) 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:
|
|
-----------
|
|
|
|
A) 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
|
|
|
|
B) 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)
|
|
------
|