Introduction

This is a plugin for OpenVPN (Community Edition) that authenticates users directly against Okta, with support for MFA.

Note: This plugin does not work with OpenVPN Access Server (OpenVPN-AS)

Requirements

This plugin requires that OpenVPN Community Edition be configured or used in the following ways:

OpenVPN must be configured to call plugins via a deferred call.
By default, OpenVPN clients must authenticate using client SSL certificates.
If authenticating using MFA, the end user will authenticate by appending their six-digit MFA token to the end of their password.

For example, if a user's password is correcthorsebatterystaple and their six-digit MFA token is 123456, they would use correcthorsebatterystaple123456 as the password for their OpenVPN client

Setup and Configuration

Verify the GPG signature on this repository

The source code for this plugin is signed using GPG.

It is recommended that this plugin be verified using the git tag -v $TAGNAME command.

For example, to verify the v0.10.0 tag, use the command below:

$ git tag -v v0.10.0

Compile the C plugin

Compile the C plugin from this directory using this command:

$ make

Install required Python packages

The Python code in this project depends on the following Python packages:

urllib3
cryptography
certifi

If you use pip to manage your Python packages, you can install these requirements using this command:

$ sudo pip install urllib3 cryptography certifi

If the pip command above doesn't work, you may need to install pip or the development software that cryptography depends on.

This project also comes with a requirements.txt file that works nicely with pip:

$ sudo pip install -r requirements.txt

Install the Okta OpenVPN plugin

You have two options to install the Okta OpenVPN plugin:

For default setups, use make install to run the install for you.
For custom setups, follow the manual installation instructions below.

If you have a default OpenVPN setup, where plugins are stored in /usr/lib/openvpn/plugins and configuration files are stored in /etc/openvpn, then you can use the make install command to install the Okta OpenVPN plugin:

$ sudo make install

Manually installing the Okta OpenVPN plugin

If you have a custom setup, follow the instructions below to install the C plugin and Python scripts that constitute the Okta OpenVPN plugin.

Manually installing the C Plugin

To manually install the C plugin, copy the defer_simple.so file to the location where your OpenVPN plugins are stored.

Manually installing the Python script

To manually install the Python scripts, copy the okta_openvpn.py, okta_pinset.py, and okta_openvpn.ini files to the location where your OpenVPN plugin scripts are stored.

Make sure that OpenVPN has a tempory directory

In OpenVPN, the "deferred plugin" model requires the use of temporary files to work. It is recommended that these temporary files be stored in a directory that only OpenVPN has access to. The default location for this directory is /etc/openvpn/tmp. If this directory doesn't exist, create it using this command:

$ sudo mkdir /etc/openvpn/tmp

Use the chown and chmod commands to set permissions approprate to your setup.

Configure the Okta OpenVPN plugin

The Okta OpenVPN plugin is configured via the okta_openvpn.ini file. You must update this file with the configuration options for your Okta organization for the plugin to work.

If you installed the Okta OpenVPN plugin to the default location, run this command to edit your configuration file.

$ sudo $EDITOR /etc/openvpn/okta_openvpn.ini

Configure OpenVPN to use the C Plugin

Set up OpenVPN to call the Okta plugin by adding the following lines to your OpenVPN server.conf configuration file:

plugin /usr/lib/openvpn/plugins/defer_simple.so /usr/lib/openvpn/plugins/okta_openvpn.py
tmp-dir "/etc/openvpn/tmp"

The default location for OpenVPN configuration files is /etc/openvpn/server.conf

Testing

The code in okta_openvpn.py has 100% test coverage. Tests are run using the "nosetests" command.

Run the commands below to set up an environment for testing:

$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt

Once that is done, run the tests with the nosetests command:

$ nosetests

To generate a code-coverage report on the tests, run nosetests with the following flags:

$ nosetests --with-coverage --cover-html

View the coverage reports by opening the cover/index.html in your favorite text editor.

Contact

Updates or corrections to this document are very welcome. Feel free to send me pull requests with suggestions.

Additionally, please send me comments or questions via email: joel.franusic@okta.com

jpf / okta-openvpn