Repository files navigation

Runs 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.

The idea of the plugin is to do as little as possible, and let the external binary do all the heavy lifting itself.

Compile the shared library withmake plugin and copyopenvpn-plugin-auth-script.so into yourlib/openvpn/plugins/ folder.

Copy your external script onto the machine in a sane place, making sure it's executable by the user openvpn is running as.

Configure the plugin in your openvpn config, passing the path to the external script as the second argument:

plugin /path/to/openvpn-plugin-auth-script.so /path/to/external/script.sh

The plugin will also pass any strings provided after the script name as arguments to the script execution:

plugin /path/to/openvpn-plugin-auth-script.so /path/to/external/script.sh arg1 arg2 argN

The 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.

It needs to:

• Be executable by the user openvpn runs as
• Readusername andpassword from theENV to check them
• Readauth_control_file from theENV and write a single character to that path to signify auth success/failure
  • Toallow authentication, write1 to the file
  • Toblock authentication, write0 to the file
• Exit with status code 0
• Not depend onPATH variable (eg, don't use/usr/bin/env in shebang)

Example env the script is called in:

PWD=/SHLVL=0auth_control_file=/tmp/openvpn_acf_9090e6750844ee26d7f23efbad0e95c2.tmpconfig=/opt/local/etc/openvpn/testvpn.confdaemon=1daemon_log_redirect=0daemon_pid=10502daemon_start_time=1488892554dev=tun0dev_type=tunifconfig_local=192.168.2.1ifconfig_remote=192.168.2.2link_mtu=1572local_port_1=1194password=bproto_1=tcp-serverredirect_gateway=0remote_port_1=1194route_gateway_1=192.168.2.2route_netmask_1=255.255.255.0route_network_1=192.168.2.0route_vpn_gateway=192.168.2.2script_context=inittun_mtu=1500untrusted_ip=192.168.3.4untrusted_port=54357username=averb=9

If you're usingstatic-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.

The format in the env password value isSCRV1:<BASE64_PASSWORD>:<BASE64_RESPONSE>

See LICENSE.