Using AUTH_NULL for custom authentication

Introduction

This document provides an overview for creating a custom post-auth script using the AUTH_NULL parameter as an added step in user authentication for OpenVPN Access Server.

With Access Server, you set up user authentication in the Admin Web UI for local authentication or external authentication using LDAP, RADIUS, SAML, or PAM. Then, when you add your custom Python script with a post-auth authentication hook, it runs during an authentication session:

  1. A user signs in to your Access Server with the default authentication method (local, LDAP, RADIUS, SAML, or PAM).
  2. Their authentication attempt succeeds.
  3. The post-auth script runs.
  4. The post-auth script has the right to block or allow the authentication based on additional authentication requirements.

Custom Authentication Script Using the AUTH_NULL parameter

One of those additional authentication requirements can use the AUTH_NULL parameter for your custom authentication system. The AUTH_NULL parameter:

  • Disables the built-in primary authentication methods — meaning that Access Server accepts all username and password combinations.
  • Access Server passes the usernames and passwords directly to the post-auth script.
  • The script assumes full responsibility for authentication.

Below is a proof-of-concept script written in Python. With this script, you can create a custom solution for authentication using your system rather than one that uses PAM, LDAP, RADIUS, or SAML.

Note: You can’t add a challenge/response script for connections that use autologin profiles, such as a server. Servers are often unattended and are issued special certificates that allow automatic authentication instead of a username/password combination.

Install or update the script

Steps:

  1. Sign in to your OpenVPN Access Server with root privileges through SSH or the server console.
  2. On your OpenVPN Access Server, download the script: https://swupdate.openvpn.net/scripts/post_auth_custom_auth.py Or, you can retrieve the file directly onto your server as root with this command:
    wget https://swupdate.openvpn.net/scripts/post_auth_custom_auth.py -O /root/customauth.py
  3. Save the file using a name of your choice. This example uses customauth.py as the file name, and the example file path is /root/customauth.py.
    • Note that if you have problems downloading the script, you may need to install/update the wget and/or ca-certificates package(s) on your system.
  4. Once you have retrieved the file, you can load the script and reload Access Server:
    cd /usr/local/openvpn_as/scripts
    ./sacli -k auth.module.post_auth_script --value_file=/root/customauth.py ConfigPut
    ./sacli start
  5. After you make your edits to the customauth.py file, use the commands listed in Step 4 to load the new script version into the configuration database and reload the new Access Server configuration.

Set up custom authentication

Once you use AUTH_NULL in your script, you must configure the credential step or authcred. AUTH_NULL disables the primary authentication method, allowing you to replace it with your custom method.

By default, the script implements a basic check. Examine the file to see which credentials are allowed to establish a connection. Python allows you to further expand on this custom script to connect it to external databases or processes that can be called upon to verify authentication.

Uninstall the script

You can uninstall the post-auth script from the configuration database with these commands:

cd /usr/local/openvpn_as/scripts
./sacli -k auth.module.post_auth_script ConfigDel
./sacli start