mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-12-01 06:24:13 +01:00
c97dac4bd9
There is no wiki for this project, that information is either in the doc folder or in the project manpages. Both of which accessible from https://developers.yubico.com/yubico-pam/ fixes #81
224 lines
8.0 KiB
Plaintext
224 lines
8.0 KiB
Plaintext
Yubico PAM Single-factor configuration guide
|
||
--------------------------------------------
|
||
|
||
Step by Step Guide for Configuration of Yubico PAM module to provide single
|
||
factor YubiKey OTP authentication for RADIUS server.
|
||
|
||
Introduction
|
||
------------
|
||
The purpose of this document is to guide readers through the configuration
|
||
steps to enable single factor authentication using YubiKey and RADIUS server
|
||
on Linux platform. This document assumes that the reader has advance knowledge
|
||
and experience in Linux system administration, particularly how to configure
|
||
PAM authentication mechanism on a Linux platform.
|
||
|
||
|
||
Details
|
||
-------
|
||
|
||
Prerequisites
|
||
-------------
|
||
|
||
Successful configuration of the Yubico PAM module to support single factor
|
||
authentication for RADIUS requires following prerequisites:
|
||
|
||
* Operating System: Any Unix operating system which supports PAM
|
||
(Pluggable Authentication Module)
|
||
(http://www.kernel.org/pub/linux/libs/pam/)
|
||
* Complier : GNU GCC complier (http://gcc.gnu.org/)
|
||
* FreeRADIUS: FreeRADIUS Version: 1.1.7 or *later*
|
||
(http://freeradius.org/download.html)
|
||
* Yubico PAM Module: Yubico PAM Module Version 1.8
|
||
(https://developers.yubico.com/yubico-pam/)
|
||
|
||
|
||
Configuration
|
||
-------------
|
||
|
||
Configuration of FreeRADIUS server to support PAM authentication :
|
||
------------------------------------------------------------------
|
||
|
||
* Edit the radiusd configuration file “/etc/raddb/radiusd.conf” to make
|
||
following changes:
|
||
------
|
||
* Change user and group to “root” to provide the root privileges to
|
||
radiusd daemon so that it can call and use pam modules for authentication.
|
||
NOTE: Generally, it is not a good security practice to assign root
|
||
privileges to a user for a daemon. However, since use of PAM requires root
|
||
privileges, this is a mandatory step here.
|
||
* In “authenticate” section uncomment pam to direct radiusd daemon to use PAM
|
||
module for authentication
|
||
------
|
||
* Edit the client configuration file “/etc/raddb/clients.conf”
|
||
------
|
||
Add sample client for testing
|
||
------
|
||
* Edit the user configuration file “/etc/raddb/users” to make following change:
|
||
------
|
||
Change "DEFAULT Auth-Type = System" to "DEFAULT Auth-Type = pam" for using
|
||
PAM modules for user authentication
|
||
------
|
||
|
||
Installation of pam_yubico module :
|
||
-----------------------------------
|
||
Build instructions for pam_yubico are available in the README.
|
||
(https://developers.yubico.com/yubico-pam/)
|
||
|
||
Configuration of pam_yubico module :
|
||
------------------------------------
|
||
Configuration instructions for pam_yubico are also available in the README.
|
||
(https://developers.yubico.com/yubico-pam/)
|
||
|
||
_Make sure you set your system up for either central authorization mapping,
|
||
or user level mapping, as this will control which users can connect to the
|
||
system using RADIUS._
|
||
|
||
Configuration of modified pam_yubico.so module at administrative level :
|
||
------------------------------------------------------------------------
|
||
|
||
Append the following line to the beginning of /etc/pam.d/radiusd file:
|
||
|
||
------
|
||
auth required pam_yubico.so id=16 debug authfile=/etc/yubikey_mappings
|
||
------
|
||
|
||
After the above configuration changes, whenever a user connects to the
|
||
server using any RADIUS 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 PublicID
|
||
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 :
|
||
------------
|
||
|
||
Although, user level configuration of pam_yubico is possible, this might not
|
||
be a desired configuration option in case of radisud daemon in most enterprise.
|
||
|
||
|
||
Configuration of selinux policy to create exception for radiusd daemon :
|
||
-----------------------------------------------------------------------
|
||
Local effective selinux policy must be updated to provide sufficient
|
||
privileges to radiusd daemon on system resources. Please follow the steps below
|
||
to configure effective selinux policy for radiusd daemon:
|
||
|
||
* Start the radiusd daemon
|
||
* Test the RADIUS authentication with the test case provided in “Testing the
|
||
configuration” section below
|
||
* As radiusd daemon doesn’t have sufficient selinux privileges to access the
|
||
system resources required for using pam modules, the RADIUS authentication
|
||
will fail.
|
||
* This will create the logs in either “/var/log/messages” or in
|
||
“/var/log/audit/audit.log” depending on the selinux configuration.
|
||
* We can use audit2allow utility to provide selinux privileges to radiusd by
|
||
using following sequence of commands:
|
||
|
||
------
|
||
[root@testsrv ~]# audit2allow -m local -l -i /var/log/messages > local.te
|
||
|
||
[root@testsrv ~]# checkmodule -M -m -o local.mod local.te
|
||
|
||
[root@testsrv ~]# semodule_package -o local.pp -m local.mod
|
||
|
||
[root@testsrv ~]# semodule -i local.pp
|
||
------
|
||
|
||
For more selinux policy updating information and explanation of above commands
|
||
please visit the following website:
|
||
|
||
http://fedora.redhat.com/docs/selinux-faq-fc5/#id2961385
|
||
|
||
|
||
Configuration of FreeRADIUS PAM file :
|
||
--------------------------------------
|
||
|
||
FreeRADIUS server first authorizes presence of user in the configured database
|
||
and then authenticates it.
|
||
|
||
In a single factor YubiKey authentication, we must provide a PAM mechanism to
|
||
authorize the presence of user.
|
||
|
||
We are using “pam_listfile.so” PAM module to provide a PAM mechanism to
|
||
authorize the presence of user. For this, we need to provide a file containing
|
||
authorized user names to the “pam_listfile.so” file. This file should contain
|
||
user names with only one user name on each line as follows:
|
||
|
||
For example:
|
||
|
||
------
|
||
paul
|
||
------
|
||
|
||
The user_name file must be created/updated manually before configuration of
|
||
Yubico PAM module for RADIUS authentication. Once this file is ready, we need
|
||
to edit the FreeRADIUS PAM configuration file “/etc/pam.d/radiusd” and replace
|
||
its contents with following lines:
|
||
|
||
------
|
||
auth sufficient pam_yubico.so id=16 debug authfile=/etc/yubikeyid
|
||
account required pam_listfile.so onerr=fail item=user sense=allow file=<Absolute path of file containing user names>
|
||
------
|
||
|
||
|
||
Test Setup :
|
||
------------
|
||
|
||
Our test environment is as follows:
|
||
|
||
* Operating System: Fedora release 8 (Werewolf)
|
||
* FreeRADIUS Server : FreeRADIUS Version 1.1.7 and Version 2.1.3
|
||
* Yubico PAM: pam_yubico Version 1.8
|
||
* "/etc/pam.d/radiusd" file:
|
||
|
||
------
|
||
auth sufficient pam_yubico.so id=16 debug authfile=/etc/yubikeyid
|
||
account required pam_listfile.so onerr=fail item=user sense=allow file=/etc/yubicousers
|
||
------
|
||
|
||
Testing the configuration :
|
||
---------------------------
|
||
|
||
We have tested the pam_yubico configuration on following Linux sever platforms:
|
||
|
||
* Fedora 8:
|
||
------
|
||
* Operating system: Fedora release 8 (Werewolf)
|
||
* FreeRADIUS Server : FreeRADIUS Version 1.1.7 and Version 2.1.3
|
||
* Yubico PAM: pam_yubico Version 1.8
|
||
------
|
||
* Fedora 6:
|
||
------
|
||
* Operating system: Fedora Core release 6 (Zod)
|
||
* FreeRADIUS Server : FreeRADIUS Version 1.1.7 and Version 2.1.3
|
||
* Yubico PAM: pam_yubico Version 1.8
|
||
------
|
||
|
||
To test the RADIUS single factor authentication with YubiKey, we can use
|
||
“radtest” radius client. The command is as follows:
|
||
|
||
------
|
||
[root@testsrv ~]# radtest {username} \
|
||
{password followed by YubiKey generated OTP} \
|
||
{radius-server}:{radius server port} \
|
||
{nas-port-number} \
|
||
{secret/ppphint/nasname}
|
||
|
||
[root@testsrv ~]# radtest test vrkvfefuitvfvgu...ildbdk 127.0.0.1 0 testing123
|
||
------
|
||
|
||
|
||
Note :
|
||
------
|
||
The FreeRADIUS server version 1.1.3 seems to have problems regarding memory
|
||
management and it may result in Segmentation Fault if configured with Yubico
|
||
PAM module. We recommend using FreeRADIUS server version 1.1.7 or above.
|