This is an OpenVPN plugin that authenticates users directly against Okta, with support for MFA.

This plugin requires that OpenVPN be configured or use in the following ways:

1. OpenVPN must be configured to call plugins via a deferred call.
2. OpenVPN clients must authenticate using client SSL certificates.
3. 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

Compile the C plugin from this directory using this command:

$ make

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

• urllib3
• m2crypto
• certifi

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

$ sudo pip install urllib3 m2crypto certifi

If the pip command above doesn't work, you may need to install pip or the development software that m2crypto depends on. On Ubuntu these packages are 'python-pip', 'python-dev', 'libssl-dev', and 'swig' which can be installed with the following command:

$ sudo apt-get install python-pip python-dev libssl-dev swig 

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

$ sudo pip install -r requirements.txt

You have two options to install the Okta OpenVPN plugin:

1. For default setups, use make install to run the install for you.
2. 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

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

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

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

In OpenVPN, the use of a "deferred plugin" requires the use of temporary files. 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.

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

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

The source code for this plugin is signed using GPG.

It is recommended that this software be verified using the gpg tag -v command.

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

$ git tag -v v0.9.1

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.

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