Duo Two-Factor Authentication for OpenVPN Access Server

Duo 2FA for OpenVPN AS doesn't support inline self-service enrollment for new Duo users. We recommend using bulk enrollment to send your users unique self-enrollment links via email. Read the enrollment documentation to learn more.

If using the OpenVPN client for incoming connections, ensure your users have version 2.2 or later.

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.

To get started securing your OpenVPN Access Server with Duo, you'll need to:

1. Sign up for a Duo account.
2. Log in to the Duo Admin Panel and navigate to Applications → Application Catalog.
3. Locate the entry for OpenVPN Access Server with the "2FA" label in the catalog. Click the + Add button to create 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 with Duo and additional application options.
4. No users can log in to new applications until you grant access. Update the User access setting to grant access to this application to users in selected Duo groups, or to all users. Learn more about user access to applications. If you do not change this setting now, be sure to update it so that your test user has access before you test your setup.
5. Download the latest duo_openvpn_as release package as a zip file from GitHub and uncompress the package on your OpenVPN AS server.

Configure the Post-Auth Script

1. Extract the Duo OpenVPN Access Server plugin downloaded from Duo's GitHub repository if you haven't already done so.

2. Open the duo_openvpn_as.py script in a text editor and fill in these required parameters where instructed:

   Key	Required?	Description
   IKEY	Required	Your integration key, obtained from the details page for the OpenVPN AS application in the Duo Admin Panel.
   SKEY	Required	Your secret key, obtained from the details page for the OpenVPN AS application in the Duo Admin Panel.
   HOST	Required	Your Duo API hostname (e.g. api-XXXXXXXX.duosecurity.com), obtained from the details page for the OpenVPN AS application in the Duo Admin Panel.

   # ------------------------------------------------------------------
   # Fill in your integration credentials on the following three lines:
   IKEY = 'INTEGRATION_KEY'
   SKEY = 'SECRET_KEY'
   HOST = 'API_HOSTNAME'
   # ------------------------------------------------------------------
   

3. Move the duo_openvpn_as.py script to the OpenVPN AS scripts folder - typically /usr/local/openvpn_as/scripts/ - and make sure it is executable.

   $ mv duo_openvpn_as.py /usr/local/openvpn_as/scripts/
    $ chmod a+x /usr/local/openvpn_as/scripts/duo_openvpn_as.py

Enable the Post-Auth Script

1. Use OpenVPN Access Server's command-line interface to set duo_openvpn_as.py as your post-auth script:

   $ /usr/local/openvpn_as/scripts/sacli -a admin_username -i -k auth.module.post_auth_script --value_file=/usr/local/openvpn_as/scripts/duo_openvpn_as.py ConfigPut

   Where admin_username is the username of an administrator on your OpenVPN Access Server instance. You'll be prompted to enter the administrator account's password.

2. Restart the service to commit your configuration changes:

   $ /usr/local/openvpn_as/scripts/sacli -a admin_username -i Reset

   Where admin_username is the username of an administrator on your OpenVPN Access Server instance. You'll be prompted to enter the administrator account's password.

Test Your Setup

After you have enabled the Duo Post-Auth script, try to log in as a regular VPN user through the OpenVPN Access Server web interface. If you are using an account which has not previously been enrolled for Duo authentication, your login attempt will be denied with a self-enrollment URL. Visit the URL, enroll your phone, and then try logging in again.

When you log in as a Duo-enrolled user, you will see a secondary prompt (either via a web browser or with a native client), with instructions to enter a Duo passcode (eg. "124356") or an alternate factor identifier:

Choose from the following factors:

push	Perform Duo Push authentication You can use Duo Push if you've installed Duo Mobile and added your account to it
phone	Perform phone callback
sms	Send a new batch of SMS passcodes Your authentication attempt will be denied. You can then authenticate with one of the newly-delivered passcodes.

You can also specify a number after the factor name if you have more than one device enrolled. So you can enter phone2 or push2 if you have two phones enrolled.

If you enable the optional AUTOPUSH setting, no secondary Duo prompt is shown and instead the user receives an automatic Duo Push request or phone call to their default device. If the user has no device activated for use with Duo Mobile or no phone capable of receiving an incoming call from Duo, the user cannot login.

Grant Access to Users

If you did not already grant user access to the Duo users you want to use this application be sure to do that before inviting or requiring them to log in with Duo.

Troubleshooting

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

Optional Settings

These optional settings may also be configured in the duo_openvpn_as.py script:

Key	Required?	Description
PROXY_HOST	Optional	Use the specified HTTP proxy for the outbound request to Duo's service. No proxy used if not set.
PROXY_PORT	Optional	Use the specified HTTP proxy port for the outbound request to Duo's service. No effect if PROXY_HOST not set.
SKIP_DUO_ON_VPN_AUTH	Optional	Do not perform Duo authentication for VPN client connections. Web interface logins still require 2FA. One of: True or False. Default: False.
AUTOPUSH	Optional	Do not show Duo factor selection and automatically send a Duo Push request to the user. One of: True or False. Default: False. Requires Duo OpenVPN AS release v2.5 or later.

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