Multi-factor and Two-factor Authentication
Multi-factor authentication ("MFA") is a method of confirming an identity by presenting two or more factors:
Two-factor authentication ("2FA") is a common form of multi-factor authentication which requires two factors.
OpenVPN and Tunnelblick support MFA by offering
Username/password authentication is done using scripts on the OpenVPN server combined with an '--auth-user-pass' option in an OpenVPN configuration file on the OpenVPN client.
When connecting to a VPN, Tunnelblick displays a window that lets the user enter their username and password. They are sent to the OpenVPN server and if approved, the connection attempt continues.
Checkboxes in the window allow the user to save the username or the username and password in the macOS Keychain. The saved credentials can be deleted by selecting the configuration in the list on the left side of the "Configurations" panel of Tunnelblick's "VPN Details" window, clicking the small "gear" icon underneath the list, and clicking "Delete Configuration's Credentials in Keychain".
OpenVPN and Tunnelblick support two different types of challenge/response authentication, starting with Tunnelblick 3.7.7beta04:
Static challenge/response authentication is done using scripts on the OpenVPN server combined with a '--static-challenge' option in the OpenVPN client's configuration file.
The --static-challenge option should be included in the client OpenVPN configuration file as
After asking for the username/password window or getting them from the Keychain, Tunnelblick will display a window with the
Dynamic challenge/response authentication is done using scripts on the OpenVPN server without anything special in the OpenVPN client's configuration file other than the usual '--auth-user-pass' option used for username/password authentication. The scripts send a specially-formatted error message which causes Tunnelblick to display a window with challenge text from the error message and a place to type in a response. The response is then sent to the OpenVPN server and if it is accepted the connection is allowed to continue.
OpenVPN requires that the '--auth-retry interact' option be specified in the client's OpenVPN configuration file for dynamic challenge/response to work. Tunnelblick makes including it in the configuration file unnecessary by making OpenVPN think the file includes the option. Note that the option has the side effect of also allowing interactive retries of ordinary username/password authentication and retries of private key authentication.
The OpenVPN Management Interface Notes contain more information about the challenge/response protocol; that document is also included in the OpenVPN source code.
Using Scripts with Hardware Tokens and Biometric Devices
Tunnelblick can support the use of hardware tokens and biometric devices by obtaining the response for a static or dynamic challenge from a script in a Tunnelblick VPN Configuration. The script typically presents the challenge to a device and returns the device's response to Tunnelblick by writing it to stdout.
The scripts must have specific names: "static-challenge-response.user.sh" and "dynamic-challenge-response.user.sh".
The scripts are run as the user with a safe set of environment variables and with the following four arguments:
If the script succeeds it should output the response to stdout and exit with an exit code of zero. No user interaction will take place.
If the script fails it should output an error message to stderr, and exit with an exit code of 1, 2, or 3: