upstream/openvpn
1
0
Fork 0
mirror of https://github.com/OpenVPN/openvpn.git synced 2026-06-09 00:42:51 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Document the --auth-token option

Browse source 
This isn't an option to be used directly in any configuration files,
but to be used via --client-connect scripts or --plugin making use of
OPENVPN_PLUGIN_CLIENT_CONNECT or OPENVPN_PLUGIN_CLIENT_CONNECT_V2.

 [v2 - Added lacking .B styling of options
     - Clarified the token life time ]

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <1474118415-14666-1-git-send-email-davids@openvpn.net>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg12506.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>
This commit is contained in:
David Sommerseth 2016-09-17 16:20:15 +03:00 committed by Gert Doering
parent 48d41413c4
commit f8a367f7c5
1 changed files with 54 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
doc/openvpn.8
View file

@ -4,7 +4,7 @@
.\" packet encryption, packet authentication, and
.\" packet compression.
.\"
.\" Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>
.\" Copyright (C) 2002-2016 OpenVPN Technologies, Inc. <sales@openvpn.net>
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License version 2
@ -34,7 +34,7 @@
.\" .ft -- normal face
.\" .in +|-{n} -- indent
.\"
.TH openvpn 8 "17 November 2008"
.TH openvpn 8 "25 August 2016"
.\"*********************************************************
.SH NAME
openvpn \- secure IP tunnel daemon.
@ -2928,6 +2928,7 @@ This is a partial list of options which can currently be pushed:
.B \-\-ip\-win32, \-\-dhcp\-option,
.B \-\-inactive, \-\-ping, \-\-ping\-exit, \-\-ping\-restart,
.B \-\-setenv,
.B \-\-auth\-token,
.B \-\-persist\-key, \-\-persist\-tun, \-\-echo,
.B \-\-comp\-lzo,
.B \-\-socket\-flags,
@ -5089,6 +5090,57 @@ This directive does not affect the
username/password. It is always cached.
.\"*********************************************************
.TP
.B \-\-auth\-token token
This is not an option to be used directly in any configuration files,
but rather push this option from a
.B \-\-client\-connect
script or a
.B \-\-plugin
which hooks into the OPENVPN_PLUGIN_CLIENT_CONNECT or
OPENVPN_PLUGIN_CLIENT_CONNECT_V2 calls. This option provides
a possibility to replace the clients password with an authentication
token during the lifetime of the OpenVPN client.
Whenever the connection is renegotiated and the
.B \-\-auth\-user\-pass\-verify
script or
.B \-\-plugin
making use of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY hook is
triggered, it will pass over this token as the password
instead of the password the user provided. The authentication
token can only be reset by a full reconnect where the server
can push new options to the client. The password the user entered
is never preserved once an authentication token have been set. If
the OpenVPN server side rejects the authentication token, the
client will receive an AUTH_FAIL and disconnect.
The purpose of this is to enable two factor authentication
methods, such as HOTP or TOTP, to be used without needing to
retrieve a new OTP code each time the connection is renegotiated.
Another use case is to cache authentication data on the client
without needing to have the users password cached in memory
during the life time of the session.
To make use of this feature, the
.B \-\-client\-connect
script or
.B \-\-plugin
needs to put
.nf
.ft 3
.in +4
push "auth\-token UNIQUE_TOKEN_VALUE"
.in -4
.ft
.fi
into the file/buffer for dynamic configuration data. This
will then make the OpenVPN server to push this value to the
client, which replaces the local password with the
UNIQUE_TOKEN_VALUE.
.\"*********************************************************
.TP
.B \-\-tls\-verify cmd
Run command
.B cmd