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