1== Introduction 2 3The 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. 4 5 6== Prerequisites 7 8Successful configuration of the Yubico PAM module to support two factor authentication for OpenVPN has the following prerequisites: 9 10Operating System:: Any Unix operating system which supports 11http://www.kernel.org/pub/linux/libs/pam[PAM] (Pluggable Authentication Module) 12Complier:: http://gcc.gnu.org[GNU GCC complier] 13Software:: 14https://developers.yubico.com/yubico-pam[Yubico PAM Module] + 15http://openvpn.net/index.php/downloads.html[OpenVPN] + 16http://freeradius.org/download.html[FreeRADIUS] + 17Pam_Radius 18 19== Configuration 20 21There are two ways OpenVPN can be configured to support two factor authentication with YubiKey. 22 23=== OpenVPN Configuration without FreeRADIUS support: 24 25In this mode of configuration, OpenVPN server will be authenticating users 26by verifying username and user’s password against system password file 27`/etc/passwd` and verifying OTP (one time password generated from YubiKey) 28against Yubico's OTP validation server. 29 30We assume that OpenVPN server is already installed on the server. 31 32==== Configuration of OpenVPN server to support PAM authentication: 33 34* Edit the OpenVPN server configuration file `/etc/openvpn/server.conf` 35 to add the following three lines to enable PAM modules for username 36 and password authentication: 37 38 plugin <Absolute path of “openvpn-auth-pam.so” file> <PAM configuration file name for OpenVPN 39 client-cert-not-required 40 username-as-common-name 41 42(for example: `plugin /usr/lib/openvpn/plugin/lib/openvpn-auth-pam.so openvpn`) 43 44 45* Edit the OpenVPN client configuration file `/etc/openvpn/client.conf` to 46 add following line to configure OpenVPN client for prompting username and 47 password: 48 49 auth-user-pass 50 51 52==== Installation of pam_yubico module: 53 54Build instructions for pam_yubico are available in its README. 55 56==== Configuration of pam_yubico module: 57 58There are two ways of user and YubiKey PublicID (token ID) mapping. 59It can be either done at administrative level or at individual user level. 60 61===== Administrative Level 62 63In Administrative level, system administrators hold right to configure 64the user and YubiKey PublicID mapping. Administrators can achieve this 65by creating a new file that contains information about the username and 66the corresponding PublicIDs of YubiKey(s) assigned. 67 68This file contains user name that is allowed to connect to the system 69using RADIUS and the PublicID of the YubiKey(s) assigned to that 70particular user. 71 72A user can be assigned multiple YubiKeys and this multikey mapping is 73supported by this file. However, presently there is no logic coded to 74detect or prevent use of same YubiKey ID for multiple users. 75 76Each record in the file should begin on a new line. The parameters in 77each record are separated by `:` character similar to `/etc/passwd`. 78 79The contents of this file are as follows: 80 81------ 82<user name>:<YubiKey PublicID>:<YubiKey PublicID>: …. 83<user name>:<YubiKey PublicID >:<YubiKey PublicID>:….. 84------ 85e.g.: 86 87------ 88paul:indvnvlcbdre:ldvglinuddek 89simon:uturrufnjder:hjturefjtehv 90kurt:ertbhunjimko 91------ 92 93The mapping file must be created/updated manually before configuration 94of Yubico PAM module for OpenVPN authentication. 95 96 97====== Configuration of modified pam_yubico.so module at administrative level: 98 99Append the following line to the beginning of /etc/pam.d/radiusd file: 100 101 auth required pam_yubico.so id=16 debug authfile=/path/to/mapping/file 102 103After the above configuration changes, whenever a user connects to the 104server using any RADIUS client, the PAM authentication interface will 105pass the control to Yubico PAM module. 106 107The Yubico PAM module first checks the presence of authfile argument 108in PAM configuration. If authfile argument is present, it parses the 109corresponding mapping file and verifies the username with corresponding 110YubiKey PublicID as configured in the mapping file. If valid, the Yubico 111PAM module extracts the OTP string and sends it to the Yubico 112authentication server or else it reports failure. If authfile argument 113is present but the mapping file is not present at the provided path PAM 114module reports failure. 115 116After successful verification of OTP Yubico PAM module from the Yubico 117authentication server, a success code is returned. 118 119 120===== User Level 121 122Although, user level configuration of pam_yubico is possible, this might 123not be a desired configuration option in case of OpenVPN daemon in most 124enterprise. 125 126====== Configuration of PAM modules for OpenVPN: 127 128To configure PAM modules for OpenVPN, create a file named 129`/etc/pam.d/openvpn` (file name must be one which is specified 130in `/etc/openvpn/server.conf` along with 'plugin' directive) 131and list all the PAM modules in this files accordingly. 132 133==== Test Setup 134 135Our test environment is as follows: 136 137Operating System:: Fedora release 8 (Werewolf) 138 139OpenVPN Server:: OpenVPN Version 2.0.9 140 141Yubico PAM:: pam_yubico Version 1.8 142 143/etc/pam.d/openvpn file:: 144---- 145auth required pam_yubico.so authfile=/etc/yubikeyid id=16 debug 146auth include system-auth 147account required pam_nologin.so 148account include system-auth 149password include system-auth 150session include system-auth 151---- 152 153==== Testing the configuration 154 155We have tested the pam_yubico configuration on following Linux sever platforms: 156 157i) Fedora 8: 158 159 Operating system: Fedora release 8 (Werewolf), 160 OpenVPN Server : OpenVPN Version 2.0.9, 161 Yubico PAM: pam_yubico Version 1.8 162 163ii) Fedora 6: 164 165 Operating system: Fedora Core release 6 (Zod), 166 OpenVPN Server: OpenVPN Version 2.0.9, 167 Yubico PAM: pam_yubico version 1.8 168 169To test the configuration, first create a couple of test users on the 170system where OpenVPN server is running and configure their YubiKey IDs 171accordingly. 172 173Please use the following command for testing: 174 175------ 176[root@testsrv ~]# openvpn /etc/openvpn/client.conf 177------ 178 179OpenVPN client will first prompt for username, enter the username. 180After that OpenVPN client will prompt for password, enter user’s password 181immediately followed by an OTP generated by a YubiKey. 182 183If OpenVPN server is configured for supporting PAM authentication, it 184will verify user authentication details even at the startup of OpenVPN 185server demon, when it is started using `init.d` script or it is 186configured to start at boot time. 187 188To avoid prompting of username and password at the startup of OpenVPN 189server demon, we can start OpenVPN Server demon at command line as 190follows instead of starting it using `init.d` script: 191 192------ 193[root@testsrv ~]# /usr/sbin/openvpn --config /etc/openvpn/server.conf --daemon openvpn 194------ 195 196We can configure OpenVPN server demon to start at boot time by 197copying the above command in `/etc/rc.local` file. 198 199=== OpenVPN Configuration with FreeRADIUS support 200 201In this type of configuration, the OpenVPN server will be using 202FreeRADIUS server for authenticating users. FreeRADIUS server will 203be verifying the authentication information received from OpenVPN 204server by verifying the username and user’s password against system 205password file `/etc/passwd` (or by other means supported by FreeRADIUS) 206and verifying the OTP (one time password) generated by a YubiKey 207with the Yubico’s OTP validation server. 208 209To configure OpenVPN with FreeRADIUS support, please follow the steps below: 210 211* Follow all the steps mentioned in the section “OpenVPN Configuration without FreeRADIUS support” to configure OpenVPN server to support PAM authentication. 212 213* https://developers.yubico.com/yubico-pam/YubiKey_and_FreeRADIUS_via_PAM.html[Install and configure FreeRADIUS server for two factor authentication]. 214 215* Install and configure pam_radius_auth.so and copy it to /lib/security directory 216 217* Create a file `/etc/pam.d/openvpn` (file name must be the one which is specified 218in `/etc/openvpn/server.conf` along with 'plugin' directive) and copy the following 219contents to the file: 220 221------ 222account required pam_radius_auth.so 223account required pam_radius_auth.so 224auth required pam_radius_auth.so no_warn try_first_pass 225------ 226 227* Create a file `/etc/raddb/server` to configure FreeRADIUS server that is 228used by `pam_radius_auth` PAM module. The content for the file is as follows: 229 230------ 231<RADIUS server fully qualified domain name/IP Address> <Shared Secret> 232 233<RADIUS server fully qualified domain name/IP Address> <Shared Secret> 234. 235. 236. 237------ 238 239e.g.: 240 241------ 242freeradius.example.com Admin456 243------ 244 245We can configure failover support for RADIUS server by creating additional 246RADIUS server entries per line of ´/etc/raddb/server´ file. 247 248==== Test Setup 249 250Our test environment is as follows: 251 252* `/etc/pam.d/openvpn` file: 253 254------ 255account required pam_radius_auth.so 256account required pam_radius_auth.so 257auth required pam_radius_auth.so no_warn try_first_pass 258------ 259 260==== Testing the configuration 261 262We have tested the pam_yubico configuration on following Linux sever platforms: 263 264* Fedora 8 265* Fedora 6 266 267To test the configuration, first create a couple of test users 268on the system where FreeRADIUS server is running and configure 269their YubiKey IDs accordingly. 270 271Please use the following command for testing: 272 273------ 274[root@varsha ~]# openvpn /etc/openvpn/client.conf 275------ 276 277OpenVPN client will first prompt for username, enter the username. 278After that OpenVPN client will prompt for password, enter user’s 279password immediately followed by an OTP generated by a YubiKey. 280