README.md
1# OpenVPN Auth Script Plugin
2
3Runs an external script to decide whether to authenticate a user or not. Useful for checking 2FA on VPN auth attempts as it doesn't block the main openvpn process, unlike passing the script to `--auth-user-pass-verify` flag.
4
5The idea of the plugin is to do as little as possible, and let the external binary do all the heavy lifting itself.
6
7## Installation
8
9Compile the shared library with `make plugin` and copy `openvpn-plugin-auth-script.so` into your `lib/openvpn/plugins/` folder.
10
11Copy your external script onto the machine in a sane place, making sure it's executable by the user openvpn is running as.
12
13Configure the plugin in your openvpn config, passing the path to the external script as the second argument:
14
15 plugin /path/to/openvpn-plugin-auth-script.so /path/to/external/script.sh
16
17The plugin will also pass any strings provided after the script name as arguments to the script execution:
18
19 plugin /path/to/openvpn-plugin-auth-script.so /path/to/external/script.sh arg1 arg2 argN
20
21## External Script requirements
22
23The script used to handle authentication has a very specific set of skills it needs, and if you don't provide those it will hunt you down in silence.
24
25It needs to:
26
27* Be executable by the user openvpn runs as
28* Read `username` and `password` from the `ENV` to check them
29* Read `auth_control_file` from the `ENV` and write a single character to that path to signify auth success/failure
30 * To **allow** authentication, write `1` to the file
31 * To **block** authentication, write `0` to the file
32* Exit with status code 0
33* Not depend on `PATH` variable (eg, don't use `/usr/bin/env` in shebang)
34
35Example env the script is called in:
36
37 PWD=/
38 SHLVL=0
39 auth_control_file=/tmp/openvpn_acf_9090e6750844ee26d7f23efbad0e95c2.tmp
40 config=/opt/local/etc/openvpn/testvpn.conf
41 daemon=1
42 daemon_log_redirect=0
43 daemon_pid=10502
44 daemon_start_time=1488892554
45 dev=tun0
46 dev_type=tun
47 ifconfig_local=192.168.2.1
48 ifconfig_remote=192.168.2.2
49 link_mtu=1572
50 local_port_1=1194
51 password=b
52 proto_1=tcp-server
53 redirect_gateway=0
54 remote_port_1=1194
55 route_gateway_1=192.168.2.2
56 route_netmask_1=255.255.255.0
57 route_network_1=192.168.2.0
58 route_vpn_gateway=192.168.2.2
59 script_context=init
60 tun_mtu=1500
61 untrusted_ip=192.168.3.4
62 untrusted_port=54357
63 username=a
64 verb=9
65
66### Static Challenge
67
68If you're using `static-challenge`, you might wonder where the response value is in the env hash. See the OpenVPN management-notes docs for more info, but it's passed as part of the password.
69
70The format in the env password value is `SCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>`
71
72## License
73
74See LICENSE.
75