mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-12-04 15:24:10 +01:00
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
|
|||
|
|
(http://opensource.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://github.com/Yubico/yubico-pam/wiki/ReadMe)
|
|||
|
|
|
|||
|
|
Configuration of pam_yubico module :
|
|||
|
|
------------------------------------
|
|||
|
|
Configuration instructions for pam_yubico are also available in the README.
|
|||
|
|
(https://github.com/Yubico/yubico-pam/wiki/ReadMe)
|
|||
|
|
|
|||
|
|
_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.
|