Okta provides a free level for their developer accounts, which is what I used for this example. I use Okta in my day job (as a sysadmin), and the setup and configuration are the same, so this is a safe avenue for exploration and testing.
The first step is to set up an account with Okta, if you don’t already have one. Go to https://developer.okta.com and click on the “Create Free Account” button. You just need to enter some basic information, answer a couple of questions, and they generate a developer instance for you. In my case, I was issued dev-141432.okta.com as my domain. Normally, for paid customers, this is <your-phrase-here>.okta.com.
Once you sign up, Okta sends you a verification email along with your username (email) and a temporary password. Upon your first login, you’re forced to change your password, set a security question, and select a “security image” from a set of 12 predefined images. After that, we’re off to the races!
The “Get started with Okta” page is shown once your account is configured. This gives you a “wizard” like interface to get things up and running.
Creating Your API Token
Click on the “Create Token” button, and I set the name of “OpenVPN Auth” for mine. It is generally recommended that you maintain different API tokens for different services or teams, so if one becomes compromised, the exposure and effort to correct are contained. Once you click the “Create Token” button after providing a name, you will be shown the API key. This is the only time you can view this key. You should copy it and save it somewhere. Losing it mandates you to delete and create a new key.
Note: API keys are valid for 30 days from creation and extended 30 days from last use.
To use MFA tokens (including the Okta or Google Authenticator App), you need to enable multi-factor (MFA) mechanisms. To do so, I found it easiest to switch from developer mode to the Classic UI (upper left corner of web page header). From there, select Security -> Multifactor. I enabled both by selecting Okta Verify (default) and changing the dropdown from Inactive to Active. In this scenario, do not enable the push notifications.
You’re welcome to enable SMS Authentication or any of the others, they are simply not covered in this article.
The next thing we need is users. For my example, I just used my admin user (with a caveat). You can create users for your employees, friends, family, whatever you need. You enter their email addresses, and Okta will send them a welcome email with a way to activate their account, just like you did earlier.
I strongly recommend creating a separate account for your user testing. If you lock out your lone admin account, the only way to unlock it is via the API (which we hope you set up and tested). You can enable additional self-help policies, but I’m not covering those in this article.
User Factor Enrollment
You can now download the Okta Verify app from your device App/Play Store. Once installed, login to the Okta website. I prefer the Classic UI over the Developer UI, and the Classic UI should be assumed in these examples. You can change from the Developer mode to the Classic UI in the site header.
Once logged in and Classic UI is enabled, select “My Apps” from the header's right side. Then select your username (dropdown) and go to your settings page and click on the green “Edit” button near the top right corner.
On the left-hand side, you’ll see a block allowing you to set up the configured MFA mechanisms. In each case, the site will prompt you to perform the steps necessary. Generally, this is downloading the app, scanning the QR code, and verifying it works by entering/validating the current MFA token.
Note that in both the case of Google Authenticator and Okta Verify, you can use any other application that can produce TOTP/HOTP responses. Some features, however, like the Okta push capability, will not function.
Integrating Okta with OpenVPN
Just like our DIY solution earlier, we simply need a script setup for the --auth-user-pass-verify option on the server side.
I’ve included a sample script the zip file mentioned earlier written in python. You’ll need to edit this script and add your stub URL (i.e., https://dev-xxxxxxx.okta.com) and your API key. Like the DIY script, this supports both only the token or a combination of password:token. If you are going to require a password in addition to the MFA token, you’ll need to flesh out that part of the script and set require_password to 1.