summaryrefslogtreecommitdiff
path: root/src/plugins/auth-pam/README.auth-pam
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
committerBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
commit9fc3b98112217f2d92a67977dbde0987cc7a1803 (patch)
tree29fcc8654ee65d9dd89ade797bea2f3d9dfd9cfd /src/plugins/auth-pam/README.auth-pam
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'src/plugins/auth-pam/README.auth-pam')
-rw-r--r--src/plugins/auth-pam/README.auth-pam54
1 files changed, 47 insertions, 7 deletions
diff --git a/src/plugins/auth-pam/README.auth-pam b/src/plugins/auth-pam/README.auth-pam
index e123690..e3ca027 100644
--- a/src/plugins/auth-pam/README.auth-pam
+++ b/src/plugins/auth-pam/README.auth-pam
@@ -7,7 +7,7 @@ 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 indepedent levels of authentication.
+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,
@@ -36,19 +36,20 @@ pairs to answer PAM module queries.
For example:
- plugin openvpn-auth-pam.so "login login USERNAME password PASSWORD"
+ 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, and
-(c) answer a "password" query with the password given by the
-OpenVPN client. This provides flexibility in dealing with the different
+"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" and "PASSWORD" are special strings which substitute
+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
@@ -59,8 +60,12 @@ is to be answered with the constant value "mydomain.com":
The following OpenVPN directives can also influence
the operation of this plugin:
- client-cert-not-required
+ 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
@@ -68,6 +73,41 @@ 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,