mirror of
https://github.com/Yubico/yubico-pam.git
synced 2024-12-11 09:24:10 +01:00
298 lines
10 KiB
Plaintext
298 lines
10 KiB
Plaintext
== Introduction
|
||
|
||
The purpose of this document is to guide readers through the configuration steps to use two factor authentication for OpenVPN 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 for OpenVPN has the following prerequisites:
|
||
|
||
Operating System::
|
||
Any Unix operating system which supports
|
||
http://www.kernel.org/pub/linux/libs/pam[PAM] (Pluggable Authentication Module)
|
||
Complier:: http://gcc.gnu.org[GNU GCC complier]
|
||
https://developers.yubico.com/yubico-pam[Yubico PAM Module]:: Version 1.8
|
||
http://openvpn.net/index.php/downloads.html[OpenVPN]:: Version 2.0.9.
|
||
http://freeradius.org/download.html[FreeRADIUS]: Version 1.1.7 or later.
|
||
Pam_Radius:: Version 1.3.17.
|
||
|
||
== Configuration
|
||
|
||
There are two ways OpenVPN can be configured to support two factor authentication with YubiKey.
|
||
|
||
=== OpenVPN Configuration without FreeRADIUS support:
|
||
|
||
In this mode of configuration, OpenVPN server will be authenticating users
|
||
by verifying username and user’s password against system password file
|
||
`/etc/passwd` and verifying OTP (one time password generated from YubiKey)
|
||
against Yubico's OTP validation server.
|
||
|
||
We assume that OpenVPN server is already installed on the server.
|
||
|
||
==== Configuration of OpenVPN server to support PAM authentication:
|
||
|
||
* Edit the OpenVPN server configuration file `/etc/openvpn/server.conf`
|
||
to add the following three lines to enable PAM modules for username
|
||
and password authentication:
|
||
|
||
plugin <Absolute path of “openvpn-auth-pam.so” file> <PAM configuration file name for OpenVPN
|
||
client-cert-not-required
|
||
username-as-common-name
|
||
|
||
(for example: `plugin /usr/lib/openvpn/plugin/lib/openvpn-auth-pam.so openvpn`)
|
||
|
||
|
||
* Edit the OpenVPN client configuration file `/etc/openvpn/client.conf` to
|
||
add following line to configure OpenVPN client for prompting username and
|
||
password:
|
||
|
||
auth-user-pass
|
||
|
||
|
||
==== Installation of pam_yubico module:
|
||
|
||
Build instructions for pam_yubico are available in its README.
|
||
|
||
==== Configuration of pam_yubico module:
|
||
|
||
There are two ways of user and YubiKey PublicID (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 PublicID mapping. Administrators can achieve this
|
||
by creating a new file that contains information about the username and
|
||
the corresponding PublicIDs of YubiKey(s) assigned.
|
||
|
||
This file contains user name that is allowed to connect to the system
|
||
using RADIUS and the PublicID of the YubiKey(s) assigned to that
|
||
particular user.
|
||
|
||
A user can be assigned multiple YubiKeys and this multikey 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 PublicID>:<YubiKey PublicID>: ….
|
||
<user name>:<YubiKey PublicID >:<YubiKey PublicID>:…..
|
||
------
|
||
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 OpenVPN authentication.
|
||
|
||
|
||
====== 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=/path/to/mapping/file
|
||
|
||
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 OpenVPN daemon in most
|
||
enterprise.
|
||
|
||
====== Configuration of PAM modules for OpenVPN:
|
||
|
||
To configure PAM modules for OpenVPN, create a file named
|
||
`/etc/pam.d/openvpn` (file name must be one which is specified
|
||
in `/etc/openvpn/server.conf` along with 'plugin' directive)
|
||
and list all the PAM modules in this files accordingly.
|
||
|
||
==== Test Setup
|
||
|
||
Our test environment is as follows:
|
||
|
||
Operating System:: Fedora release 8 (Werewolf)
|
||
|
||
OpenVPN Server:: OpenVPN Version 2.0.9
|
||
|
||
Yubico PAM:: pam_yubico Version 1.8
|
||
|
||
/etc/pam.d/openvpn file::
|
||
----
|
||
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 include system-auth
|
||
----
|
||
|
||
==== Testing the configuration
|
||
|
||
We have tested the pam_yubico configuration on following Linux sever platforms:
|
||
|
||
i) Fedora 8:
|
||
|
||
Operating system: Fedora release 8 (Werewolf),
|
||
OpenVPN Server : OpenVPN Version 2.0.9,
|
||
Yubico PAM: pam_yubico Version 1.8
|
||
|
||
ii) Fedora 6:
|
||
|
||
Operating system: Fedora Core release 6 (Zod),
|
||
OpenVPN Server: OpenVPN Version 2.0.9,
|
||
Yubico PAM: pam_yubico version 1.8
|
||
|
||
To test the configuration, first create a couple of test users on the
|
||
system where OpenVPN server is running and configure their YubiKey IDs
|
||
accordingly.
|
||
|
||
Please use the following command for testing:
|
||
|
||
------
|
||
[root@testsrv ~]# openvpn /etc/openvpn/client.conf
|
||
------
|
||
|
||
OpenVPN client will first prompt for username, enter the username.
|
||
After that OpenVPN client will prompt for password, enter user’s password
|
||
immediately followed by an OTP generated by a YubiKey.
|
||
|
||
If OpenVPN server is configured for supporting PAM authentication, it
|
||
will verify user authentication details even at the startup of OpenVPN
|
||
server demon, when it is started using `init.d` script or it is
|
||
configured to start at boot time.
|
||
|
||
To avoid prompting of username and password at the startup of OpenVPN
|
||
server demon, we can start OpenVPN Server demon at command line as
|
||
follows instead of starting it using `init.d` script:
|
||
|
||
------
|
||
[root@testsrv ~]# /usr/sbin/openvpn --config /etc/openvpn/server.conf --daemon openvpn
|
||
------
|
||
|
||
We can configure OpenVPN server demon to start at boot time by
|
||
copying the above command in `/etc/rc.local` file.
|
||
|
||
=== OpenVPN Configuration with FreeRADIUS support
|
||
|
||
In this type of configuration, the OpenVPN server will be using
|
||
FreeRADIUS server for authenticating users. FreeRADIUS server will
|
||
be verifying the authentication information received from OpenVPN
|
||
server by verifying the username and user’s password against system
|
||
password file `/etc/passwd` (or by other means supported by FreeRADIUS)
|
||
and verifying the OTP (one time password) generated by a YubiKey
|
||
with the Yubico’s OTP validation server.
|
||
|
||
To configure OpenVPN with FreeRADIUS support, please follow the steps below:
|
||
|
||
* Follow all the steps mentioned in the section “OpenVPN Configuration without FreeRADIUS support” to configure OpenVPN server to support PAM authentication.
|
||
|
||
* https://developers.yubico.com/yubico-pam/YubiKey_and_FreeRADIUS_via_PAM.html[Install and configure FreeRADIUS server for two factor authentication].
|
||
|
||
* Install and configure pam_radius_auth.so and copy it to /lib/security directory
|
||
|
||
* Create a file `/etc/pam.d/openvpn` (file name must be the one which is specified
|
||
in `/etc/openvpn/server.conf` along with 'plugin' directive) and copy the following
|
||
contents to the file:
|
||
|
||
------
|
||
account required pam_radius_auth.so
|
||
account required pam_radius_auth.so
|
||
auth required pam_radius_auth.so no_warn try_first_pass
|
||
------
|
||
|
||
* Create a file `/etc/raddb/server` to configure FreeRADIUS server that is
|
||
used by `pam_radius_auth` PAM module. The content for the file is as follows:
|
||
|
||
------
|
||
<RADIUS server fully qualified domain name/IP Address> <Shared Secret>
|
||
|
||
<RADIUS server fully qualified domain name/IP Address> <Shared Secret>
|
||
.
|
||
.
|
||
.
|
||
------
|
||
|
||
e.g.:
|
||
|
||
------
|
||
freeradius.example.com Admin456
|
||
------
|
||
|
||
We can configure failover support for RADIUS server by creating additional
|
||
RADIUS server entries per line of ´/etc/raddb/server´ file.
|
||
|
||
==== Test Setup
|
||
|
||
Our test environment is as follows:
|
||
|
||
i) Operating System: Fedora release 8 (Werewolf)
|
||
ii) FreeRADIUS Server : FreeRADIUS Version 1.1.7
|
||
iii) Pam_Radius: pam_radius_auth 1.3.17
|
||
iv) Yubico PAM: pam_yubico Version 1.8
|
||
v) `/etc/pam.d/openvpn` file:
|
||
|
||
------
|
||
account required pam_radius_auth.so
|
||
account required pam_radius_auth.so
|
||
auth required pam_radius_auth.so no_warn try_first_pass
|
||
------
|
||
|
||
==== Testing the configuration
|
||
|
||
We have tested the pam_yubico configuration on following Linux sever platforms:
|
||
|
||
===== Fedora 8
|
||
Operating system:: Fedora release 8 (Werewolf)
|
||
OpenVPN Server:: OpenVPN Version 2.0.9
|
||
Yubico PAM:: pam_yubico Version 1.8
|
||
FreeRADIUS Server:: FreeRADIUS Server Version 1.1.7
|
||
Pam_radius:: pam_radius_auth Version 1.3.17
|
||
|
||
===== Fedora 6
|
||
Operating system:: Fedora Core release 6 (Zod)
|
||
OpenVPN Server:: OpenVPN Version 2.0.9
|
||
Yubico PAM:: pam_yubico version 1.8
|
||
FreeRADIUS Server:: FreeRADIUS Server Version 1.1.7
|
||
Pam_radius:: pam_radius_auth Version 1.3.17
|
||
|
||
To test the configuration, first create a couple of test users
|
||
on the system where FreeRADIUS server is running and configure
|
||
their YubiKey IDs accordingly.
|
||
|
||
Please use the following command for testing:
|
||
|
||
------
|
||
[root@varsha ~]# openvpn /etc/openvpn/client.conf
|
||
------
|
||
|
||
OpenVPN client will first prompt for username, enter the username.
|
||
After that OpenVPN client will prompt for password, enter user’s
|
||
password immediately followed by an OTP generated by a YubiKey.
|
||
|
||
|
||
NOTE: Please use OpenVPN server Version 2.0.9 (Latest Stable Version), as older and newer beta versions have problems with PAM libraries. RADIUS authentication will fail if it is configured with older or latest beta versions of OpenVPN Server.
|