- 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 administrative interface or with Duo’s bulk enrollment feature (which sends personalized enrollment links via email).
To get started with your OpenVPN integration, you’ll need to:
- Sign up for a Duo account
- Create a new OpenVPN integration to get an integration key, secret key, and API hostname. (See Getting Started for help.)
- Download the OpenVPN integration package from our duo_openvpn GitHub respository
This integration communicates with Duo’s service on TCP port 443. Also, we do not recommend locking down your firewall to individual IP addresses, since these may change over time to maintain our service’s high availability.
Build and Install the Plugin
To get started with the Duo OpenVPN plugin, download the OpenVPN integration package. Then simply extract, build, and install the plugin.
$ tar zxf duosecurity-duo_openvpn-463f56e.tar.gz $ cd duosecurity-duo_openvpn-463f56e $ make && sudo make install
The duo_openvpn.so plugin and duo_openvpn.py helper script will be installed into /opt/duo.
Configure the Server
Open your OpenVPN server configuration file (eg. /etc/openvpn/openvpn.conf) and append the following line to it:
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 of your integration.
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 re-authenticate with Duo. This setting defaults to 3600 seconds, which means your users must re-authenticate ever hour. If your user’s VPN client saves the password and automatically re-authenticates 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:
Old versions of OpenVPN may fail to connect with reneg-sec set to 0. If your OpenVPN version is below 2.2, then you should instead set reneg-sec to a very large value.
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:
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:
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. <firstname.lastname@example.org>
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 a user authenticates, they will be prompted by their OpenVPN client to provide an additional username and password. The username field can be ignored since Duo will pull the real username from common name (CN) field of the provided certificate. In the password field, the user can type a Duo passcode (eg. “124356”):
username: <ignored> password: 123456
In addition to entering passcodes in the password field, the user may also enter an alternate factor identifier. The user may choose from the following factor identifiers:
|phone||perform phone callback|
perform Duo Push authentication
Note that you can only use Duo Push if you have successfully enrolled your phone for it
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
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.
Returning to the previous example, if you wanted to use Duo Push (rather than a passcode) to authenticate, you would enter:
username: <ignored> password: push
- Open VPN connection initiated
- Primary authentication
- Open VPN connection established to Duo Security over TCP port 443
- Secondary authentication via Duo Security’s service
- Open VPN receives authentication response
- Open VPN session logged in