This guide will show you how to configure Duo Security into OpenVPN Community Open Source Project.
Note: If you’re using OpenVPN Access server, the instructions provided by Duo are here: https://duo.com/docs/openvpn-as
Pre-Requisites
This guide assumes:
- OpenVPN server is already configured
- Duo is rolled out / you have Duo Admin access
I highly recommend taking a full VM backup of your OpenVPN server before continuing. For testing, I recommend restoring the your OpenVPN VM with a new UUID. This will allow you to configure everything in a test environment without it impacting your live environment.
For testing, just disable the NIC of the production server and enable the test server.
Are you running the Community or Access Server version?
Wondering which version of OpenVPN you are using? There is a couple ways to check.
If you log into a web-based system to manage the configuration, certs, users access control, etc – then you are using the Access Server version. The instructions in this guide are for the Community Open Source Project. I have OpenVPN installed on a Ubuntu VM.
Step 1: Read the Duo OpenVPN Documentation page
I highly recommend reading through this Duo Help page and viewing their setup video. It’s honestly not hard to set this up, even if you have very little Linux or Ubunut experience, but I still recommend reading that doc in it’s entirety before you begin.
There’s several missing steps (particularly in the testing phase) that you’ll find useful in my post vs. theirs, so that’s why I recommend reading both.
Step 2: Protect Application in Duo
Log into your Duo Admin Panel.
Click Applications > Protect an Application and search for OpenVPN.
Choose OpenVPN (not OpenVPN Access Server) Then click Protect.
You should see your Integration Key, Secret key, and API Hostname. (You will need those later.)
Scroll down and change Username Normalization to Simple. This makes it so that that DOMAIN\username, username@example.com, and username are treated as the same user.
Of course, this also depends on how you issue your OpenVPN certs to employees. If you issue OpenVPN certs with unique Common Names (CN), then you want to make sure the CN of the client config matches the Duo username.
If users have multiple OpenVPN certs or different CN names than what Duo shows, you can create a Duo “username alias“. More details on aliases in Optional Step 2 below.
Click SAVE once complete.
Step 3: Download Duo OpenVPN Plugin
Download the plugin from here: https://github.com/duosecurity/duo_openvpn/archive/2.4.tar.gz
Download this directly from your Ubuntu VM so it saves to your Ubuntu ‘Downloads’ directory. If you download locally, upload to a cloud service like Onedrive and create a shareable link to browse to from within the Ubuntu VM.
Step 4: Extract and Install Plugin
The plugin should save to the Downloads folder. Open a terminal and change the directory (Note: capitalization matters for file paths!)
cd ~/DownloadsThen, type this to extract the file:
Tar zxf duo_openvpn-2.4.tar.gzNow, install the extracted file by typing this:
Make && sudo make installIf you receive an error that the make command is not installed, it will prompt you to install it. Type this to install the necessary components to use the Make command: sudo apt-get install build-essential and then run the command above again.
The duo_openvpn.so plugin and duo_openvpn.py Python helper script will be installed into /opt/duo. Confirm those files exist before continuing.
Step 5: Edit Server Configuration File
First, find out what OpenVPN version you are running. Open a terminal and type this to check:
openvpn --versionNext, open the server.conf file. It is located either:
- /etc/openvpn/openvpn.conf OR
- /etc/openvpn/server.conf
Browse to it by changing directories.
cd /etc/openvpnThen, open server.conf in a nano file editor (This will require the Ubuntu admin password, so make sure you have that handy) :
sudo nano server.confAdd the line below, replacing IKEY SKEY and HOST with the details from your Duo Admin panel.
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 HOSTAnd finally, we recommend setting the reneg-sec option. By default, OpenVPN reauthenticates every 3600 seconds (1 hour), which means if you didn’t set the reneg-sec option – users would have to verify their identity via Duo Push every 60 minutes.
Add this line below the line you just added:
reneg-sec 0If you want to set it for 24 hours, you’d change it to reneg-sec 86400.
Step 6: Edit the Client Certificates
If you’ve already issued OpenVPN certificates to your employees, they’ll need to add two lines to their configuration file. These are typically located in C:\users\USERNAME\OpenVPN\config and can be edited using Notepad.
reneg-sec 0
auth-user-passThe reneg-sec 0 line must match whatever you specified in the server.conf file. The auth-user-pass line will display a popup box like the image below & prompt them to enter a username and password.
Step 7: Plan Your Maintenance & Testing Window
Unless you plan on creating new firewall rules specifically for this OpenVPN test server, plan a maintenance window for testing Duo on your OpenVPN server. Inform employees than the VPN will be down for planned maintenance. You can install and configure everything in advance.
On the night you’ll be testing, just disable the network adapter on your current OpenVPN server and enable it on your Duo test OpenVPN server. That way, if you run into any issues – you can simply power off the test VM and turn on the production one.
(Optional Step 1) Create or Edit Duo Policy
Log back into the Duo Admin Panel > Policies. If your Global Policy is set to “allow unenrolled users to pass through without two-factor authentication“, then you’ll want to follow this optional step.
Instead of editing the Global Policy, let’s create a new Duo policy just for the OpenVPN application. Scroll to the bottom and click New Policy.
Create a new policy and name it OpenVPN Force Duo Policy and specify the fields below.
Then, go to Applications > OpenVPN and add the new policy to the app. This will prevent anyone from connecting to your corporate VPN without having a Duo account.
Why configure OpenVPN app this way in Duo?
If users have mismatching CN’s (i.e. – their OpenVPN CN is smarthomepursuits2 but their Duo username is smarthomepursuits), then the Global Policy would allow the smarthomepursuits2 user to connect to the VPN with Duo, which could be considered a security risk if you weren’t aware that they could do that.
If you don’t set Optional Step 1 up, the Duo logs do show the “unenrolled but authenticated” users which is nice. But it’s easier to stay on top of this beforehand.
(Optional Step 2): Add Duo Aliases (if applicable)
Another way to tackle mismatched Duo usernames vs CN name is to add their CN as an alias in Duo.
Click Users > search for the user > Edit > add CN as an alias:
If the user has smarthomepursuits2 as their Common Name (CN) of their client configuration file, and you add it as an alias in Duo, they will still receive the Duo notifications like expected.
Step 8: Test OpenVPN Integration with Duo
When you authenticate, your OpenVPN client will prompt for a username and password. The username can actually be ignored because it pulls the username from the CN field of the configuration file.
If you save the username and password, it will automatically send a Duo push notification after 5 seconds.
Duo Push Users:
If you want to use Duo Push to authenticate, they would would enter this in the popup box.
username: <ignored>
password: pushHint: You can replace push with “sms”, or “phone” as well.
Yubikey Users
If you have users using hardware tokens (such as a Yubikey), I can confirm that Duo and OpenVPN work great with Yubikeys. Yubikey or hardware token users don’t need to type anything in – they just enter a username (again – doesn’t matter what they enter here) and tap the gold circle on the Yubikey for it to autofill the password.
username: <ignored>
password: tap Yubikey to autofillTroubleshooting Tips
If you aren’t receiving Duo push notifications, that probably means port 443 isn’t open on the OpenVPN interface of your firewall. Check your firewall rules.
I also wasn’t able to get “phone” working, but none of our employees authenticate to Duo using phone calls anyway so it wasn’t a huge issue for us.
Rollout Tips
If you’ve already issues VPN certs, I recommend sending out a company email with instructions on how to edit this file themselves, along with a due date when you’ll be flipping OpenVPN to use Duo. A week to get the file edited should be more than reasonable.
Also, the client configuration file can be edited before flipping to the new Duo OpenVPN server. Yes, users will see the box asking for a username and password for a few days, but you can enter anything in and it will let your users connect.
This is great way to get a large percentage of users to update their client config file before you make the switch.
Is it possible to have OpenVPN send an automatic push to authenticate?
Yes, but I highly recommend you don’t configure this.
I’m not including the code in this post, but if you are brave enough to attempt this, Duo has a help article here.
Why? The second after you add that line to the server.conf file during testing – it will send Duo push notifications to EVERY Duo user currently connected to OpenVPN, asking them to authenticate their VPN connection.
I learned this the hard way. It resulted in hundreds of denied connections, fraudulent reports, and a bunch of locked out Duo user accounts – all after hours on a Friday night:
Wrapping Up
I wasn’t able to find step-by-step instructions like this anywhere, so hopefully this guide is straightforward enough for you to follow! Even still, it took me less than a couple hours from start to finish. I estimate this could be completed in an hour, aside from testing after hours.
Good luck – let me know in the comments if this Duo OpenVPN setup guide was helpful to you!
My Homelab Equipment
Here is some of the gear I use in my Homelab. I highly recommend each of them.
- Server 2019 w/ Hyper-V
- Case: Fractal Design Node 804
- Graphics Card: NVIDEA Quadro K600
- CPU: AMD Ryzen 7 2700
The full list of server components I use can be found on my Equipment List page.
