openvpn-auth-pam

SYNOPSIS

The openvpn-auth-pam module implements username/password
authentication via PAM, and essentially allows any authentication
method supported by PAM (such as LDAP, RADIUS, or Linux Shadow
passwords) to be used with OpenVPN.  While PAM supports
username/password authentication, this can be combined with X509
certificates to provide two independent levels of authentication.

This module uses a split privilege execution model which will
function even if you drop openvpn daemon privileges using the user,
group, or chroot directives.

BUILD

To build openvpn-auth-pam, you will need to have the pam-devel
package installed.

Build with the "make" command.  The module will be named
openvpn-auth-pam.so

USAGE

To use this plugin module, add to your OpenVPN config file:

  plugin openvpn-auth-pam.so service-type

The required service-type parameter corresponds to
the PAM service definition file usually found
in /etc/pam.d.

This plugin also supports the usage of a list of name/value
pairs to answer PAM module queries.

For example:

  plugin openvpn-auth-pam.so "login login USERNAME password PASSWORD pin OTP"

tells auth-pam to (a) use the "login" PAM module, (b) answer a
"login" query with the username given by the OpenVPN client,
(c) answer a "password" query with the password, and (d) answer a
"pin" query with the OTP given by the OpenVPN client.
This provides flexibility in dealing with different
types of query strings which different PAM modules might generate.
For example, suppose you were using a PAM module called
"test" which queried for "name" rather than "login":

  plugin openvpn-auth-pam.so "test name USERNAME password PASSWORD"

While "USERNAME" "COMMONNAME" "PASSWORD" and "OTP" are special strings which substitute
to client-supplied values, it is also possible to name literal values
to use as PAM module query responses.  For example, suppose that the
login module queried for a third parameter, "domain" which
is to be answered with the constant value "mydomain.com":

  plugin openvpn-auth-pam.so "login login USERNAME password PASSWORD domain mydomain.com"

The following OpenVPN directives can also influence
the operation of this plugin:

  verify-client-cert none
  username-as-common-name
  static-challenge

Use of --static challenege is required to pass a pin (represented by "OTP" in
parameter substitution) or a second password.

Run OpenVPN with --verb 7 or higher to get debugging output from
this plugin, including the list of queries presented by the
underlying PAM module.  This is a useful debugging tool to figure
out which queries a given PAM module is making, so that you can
craft the appropriate plugin directive to answer it.

Since running OpenVPN with verb 7 is quite verbose, alternatively
you can put

   verb 3
   setenv verb 9

in the openvpn config which will only increase logging for this plugin.


ASYNCHRONOUS OPERATION

Sometimes PAM modules take very long to complete (for example, a LDAP
or Radius query might timeout trying to connect an unreachable external
server).  Normal plugin auth operation will block the whole OpenVPN
process in this time, that is, all forwarding for all other clients stops.

The auth-pam plugin can operate asynchronously ("deferred authentication")
to remedy this situation.  To enable this, put

  setenv deferred_auth_pam 1

in your openvpn server config.  If set, this will make the "PAM background
process" fork() and do its job detached from OpenVPN.  When finished, a
status file is written, which OpenVPN will then pick up and read the
success/failure result from it.

While the plugin is working in the background, OpenVPN will continue to
service other clients normally.

Asynchronous operation is recommended for all PAM queries that could
"take time" (LDAP, Radius, NIS, ...).  If only local files are queried
(passwd, pam_userdb, ...), synchronous operation has slightly lower
overhead, so this is still the default mode of operation.


CAVEATS

This module will only work on *nix systems which support PAM,
not Windows.