Multi-factor and Two-factor Authentication

Multi-factor authentication ("MFA") is a method of confirming an identity by presenting two or more factors:

• Something the user knows
• Something the user has
• Something the user is

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, which can prove the user knows something
• challenge/response authentication, which can prove the user has something or the user is something

Username/Password Authentication

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

Challenge/Response Authentication

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

static-challenge  <text>  <echo>

where <text> is the text that is presented to the user, and <echo> is 0 to indicate that the user's response should not be echoed, or 1 to indicate the user's response should be echoed. (The <text> should be quoted if it contains spaces or other special characters.)

After asking for the username/password window or getting them from the Keychain, Tunnelblick will display a window with the <text> and a place to type in a response. The username, password, and response are then sent to the OpenVPN server and if the are accepted the connection attempt is allowed to continue.

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:

1. The challenge string.
2. The name of the configuration.
3. The localized name of the configuration, which may be the same as the name.
4. Either 'echo' or 'noecho' to indicate whether or not the response should be shown to the user.

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:

• Exit code 1: The configuration is disconnected and Tunnelblick displays a window with the error message and an "OK" button.

• Exit code 2: The configuration is disconnected and Tunnelblick displays a window with the error message and "OK" and "Retry" buttons. If the user clicks "Retry", Tunnelblick will attempt to connect to the VPN again after the disconnection is complete.

• Exit code 3: The configuration is disconnected and Tunnelblick displays a window with the error message and "OK", "Retry", and "Retry with manual response" buttons. If the user clicks "Retry", Tunnelblick will attempt to connect to the VPN again after the disconnection is complete. If the user clicks "Retry with manual response", Tunnelblick will attempt to connect to the VPN again after the disconnection is complete but (for that one connection attempt only) will present the challenge to the user and obtain a response as if the script was not present. This can be useful when the usual authentication device is not available and an alternate method can be used.

For more information about these and other scripts in Tunnelblick VPN Configurations, see Using Scripts.