Duo Two-Factor Authentication for OpenVPN

First Steps

Before moving on to the deployment steps, it's a good idea to familiarize yourself with Duo administration concepts and features like options for applications, available methods for enrolling Duo users, and Duo policy settings and how to apply them. See all Duo Administrator documentation.

Please note:

• Duo only integrates with OpenVPN servers that employ certificate authentication and use a unique common name (CN) in each user's cert. Support for OpenVPN deployments with password authentication may be supported in the future.
• Users will provide a passcode or factor identifier (eg. "push", "phone", "sms") as their OpenVPN password.
• Inline self-enrollment is not supported since OpenVPN doesn't offer a web interface for login. Administrators should enroll users ahead of time, either manually through the Duo Admin Panel or with Duo's bulk enrollment (which sends personalized enrollment links via email).

To get started with Duo for OpenVPN, you'll need to:

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications → Protect an Application.
3. Locate the entry for OpenVPN in the applications list. Click Protect to the far-right to configure the application and get your integration key, secret key, and API hostname. You'll need this information to complete your setup. See Protecting Applications for more information about protecting applications in Duo and additional application options.
4. Download the latest duo_openvpn release package as a zip file from GitHub and uncompress the package on your OpenVPN server.
5. Ensure Python 3 or 2.7 is installed on your OpenVPN server.

Video Overview

Build and Install the Plugin

To get started with the Duo OpenVPN plugin, download the Duo OpenVPN v2.4 plugin. Then simply extract, build, and install the plugin.

$ tar zxf 2.4.tar.gz
$ cd duo_openvpn-2.4
$ make && sudo make install

The duo_openvpn.so plugin and duo_openvpn.py Python helper script will be installed into /opt/duo.

Configure the Server

Open your OpenVPN server configuration file (e.g. /etc/openvpn/openvpn.conf or /etc/openvpn/server.conf) and append the following line to it:

OpenVPN 2.4 and later:

plugin /opt/duo/duo_openvpn.so 'IKEY SKEY HOST'

OpenVPN 2.3 or earlier:

plugin /opt/duo/duo_openvpn.so IKEY SKEY HOST

Be sure to replace IKEY, SKEY, and HOST on the plugin line with the integration key, secret key, and API hostname from your OpenVPN application's properties page in the Duo Admin Panel.

We also recommend setting the reneg-sec option in the server configuration file. This option will determine how often OpenVPN forces a renegotiation, thereby requiring the user to reauthenticate with Duo. This setting defaults to 3600 seconds, which means your users must reauthenticate every hour. If your user's VPN client saves the password and automatically reauthenticates with it, this may cause issues with the user receiving unexpected push notifications or their client replaying a one-time passcode. Therefore, we recommend disabling reneg-sec by setting it to 0 in your server configuration file:

reneg-sec 0

Save the configuration file and restart the OpenVPN server for the changes to take effect.

Configure the Client

Ensure that the following line is present in the OpenVPN client configuration file of all of your users:

auth-user-pass

The auth-user-pass line in the client config will cause the OpenVPN client to prompt the user for an additional password (described in more detail below) to authenticate.

If you specified the reneg-sec option in the server configuration above, be sure to also include it in your client configuration file:

reneg-sec 0

You may need to enable the dynamic challenge-response mechanism in your OpenVPN client. This mechanism is supported in the open-source client starting with version 2.2, but you usually must enable it explicitly.

First, make sure you’re running version 2.2 or later of the openvpn client:

$ openvpn --version
OpenVPN 2.2.1 x86_64-linux-gnu [SSL] [LZO2] [EPOLL] [PKCS11] [eurephia] [MH] [PF_INET6] [IPv6 payload 20110424-2 (2.2RC2)] built on Mar 30 2012
Originally developed by James Yonan
Copyright (C) 2002-2010 OpenVPN Technologies, Inc. <sales@openvpn.net>

Set the auth-retry option to a value of interact when running the client. For example:

$ openvpn --config client.ovpn --auth-retry interact

Test Your Setup

When OpenVPN is configured with certificate authentication as the primary authentication factor, Duo uses the OpenVPN password field as the input mechanism for the secondary authentication factor.

When you authenticate, your OpenVPN client to provide an additional username and password. The username field can usually be ignored since Duo will pull the real username from common name (CN) field of the provided certificate. Some OpenVPN clients won't let you submit a blank username. In that case, type something in that field.

In the password field, you can enter the name of a Duo authentication method. Choose from the following factors:

phone	Perform phone callback. Press the specified key on your phone to approve.
push	Perform Duo Push authentication. Note that you can only use Duo Push if you have successfully activated the Duo Mobile app on your phone.
sms	Send a new batch of SMS passcodes. If you select this factor, then your authentication attempt will be denied, but you will also receive new SMS passcodes. You can then proceed to authenticate again with one of the newly-delivered passcodes.
a passcode	Enter a passcode value from a hardware token, sent via SMS, generated by Duo Mobile, or a bypass code provided by your Duo administrator.

The number following the factor identifier identifies which enrolled device you wish to use to authentication. So, if you have two phones provisioned, you can also enter phone2, push2, etc.

So, if you wanted to use Duo Push to authenticate, you would enter:

username: <ignored>
password: push

If you'd like to use a Duo passcode instead (eg. "124356"), enter:

username: <ignored>
password: 123456

Troubleshooting

Need some help? Take a look at the OpenVPN Frequently Asked Questions (FAQ) page or try searching our OpenVPN Knowledge Base articles or Community discussions. For further assistance, contact Support.

Network Diagram

1. Open VPN connection initiated
2. Primary authentication
3. Open VPN connection established to Duo Security over TCP port 443
4. Secondary authentication via Duo Security’s service
5. Open VPN receives authentication response
6. Open VPN session logged in