Creating a custom authentication system with a Python script

Upgrade to Latest Version

Introduction

Here we provide documentation on setting up a custom authentication method using OpenVPN Access Server’s Post-Auth Script (PAS) functionality. You can extend Access Server’s built-in authentication methods using a PAS in Python3 language. For example, it can supplement the built-in authentication systems with a custom MFA. Here, we provide an example of using it to add an entirely new custom authentication method which we refer to as PAS-only authentication.

Access Server supports using PAS-only authentication together with the built-in authentication systems. Configuring multiple authentication methods lets you set an authentication method per group or per user. 

Note: Our sample post-auth script requires Access Server 2.11.1 or higher.

For more about post_auth scripts, refer to Post-auth Programming Notes And Examples.

Important warning

PAS-only authentication aims to allow the administrator of the Access Server to implement a completely custom authentication system. That means responsibility for handling the authentication is shifted out of OpenVPN Access Server and into the post-auth script. It is up to the creator/maintainer of this script to ensure that it is safe to use. It is important to understand that with the use of PAS-only, any authentication problems are no longer the responsibility of the OpenVPN Access Server program.

PAS-only authentication

We provide a sample script for PAS-only authentication that shows how to implement your custom authentication system in Access Server. In the sample script, we simply check the credentials the user provides against hard-coded credentials.

Note: The programmer must replace these hard-coded credentials with their own custom authentication logic. The hard-coded credentials are just to demonstrate the concept.

The difference between a post-auth script that only extends built-in authentication methods and one that can implement PAS-only authentication is the presence of these two parameters:

  • RETAIN_PASSWORD=true — credentials entered by the user are made available to the script.
  • AUTH_NULL=true — bypass Access Server authentication for PAS-only users and let the script handle it.

Once you load a post-auth script with the above two parameters and enable it, Access Server allows you to select PAS-only authentication for all users or specific users and groups. For users authenticated against PAS-only authentication, their credentials are passed transparently through Access Server to the post-auth script responsible for approving or denying their authentication request.

How to install/update the script

In our documentation, we assume you’re logged on through SSH or the console of your server running the OpenVPN Access Server with root privileges. The script itself is available from our website at the URL mentioned below. Save the script file somewhere on the Access Server, even if just temporarily. The filename that you use is not important, but in our documentation, we will assume that it is pas_only.py, stored in the following folder: /root/pas_only.py

PAS-only Script URL: https://swupdate.openvpn.net/scripts/post_auth_pas_only.py

You can retrieve the file directly on your server as root user with this command:

wget https://swupdate.openvpn.net/scripts/post_auth_pas_only.py -O /root/pas_only.py

Note: If you have problems downloading the script this way, you may need to install/update the wget and/or ca-certificates package(s) on your system.

Once you’ve saved the script on your Access Server, you can load the script and reload Access Server:

cd /usr/local/openvpn_as/scripts
./sacli --key "auth.module.post_auth_script" --value_file="/root/pas_only.py" ConfigPut
./sacli start

Any time you change the pas_only.py file, ensure you use the above commands to load the new version of the script into the configuration database and reload the configuration of the Access Server again.

Activating and using PAS-only authentication

The first time you install the PAS-only script, you must enable the PAS-only authentication system and restart the Access Server service with the following commands: 

cd /usr/local/openvpn_as/scripts
./sacli --key "auth.pas_only.0.enable" --value "true" ConfigPut
service openvpnas restart

You can now enable PAS-only authentication as the default authentication method or for specific users or groups:

  1. Sign in to the Admin Web UI and enable PAS-only authentication as the default, for a group, or for a user:
    1. Enable PAS-only as default: Click Authentication > Settings, select PAS only as the default authentication, and save settings.
    2. Enable PAS-only for a group: Click User Management > Group Permissions; click More Settings for the desired group; click PAS only for the auth method and save settings.
    3. Enable PAS-only for a user: Click User Management > User Permissions; click More Settings for the desired user; click PAS only for the auth method and save settings.

How to uninstall the script

The script is loaded into the configuration database, and you can use the commands below to remove it. Note that this action does not remove the authentication methods assignments already saved in the database, but you can clear those up in the Admin Web UI or via the command line utilities.

To uninstall/remove PAS only authentication script:

cd /usr/local/openvpn_as/scripts
./sacli --key "auth.pas_only.0.enable" ConfigDel
./sacli --key "auth.module.post_auth_script" ConfigDel
service openvpnas restart

Custom authentication with a cluster setup

If you use custom authentication with a cluster of Access Servers, ensure the following:

  1. Each node is on Access Server 2.11.1 or newer.
  2. Load and enable PAS-only authentication on all nodes.

Note: We recommend you run the latest version of Access Server with your cluster nodes and that they all run the same version.

How to debug any problems

There is a tool called authcli in the /usr/local/openvpn_as/scripts/ folder that can help to debug authentication sessions from the command line, and it provides information about what user properties are applied. You can, for example, run the following command to see the properties set for the user "test". The output includes any parameters that the post-auth script adds to the user. You can add the -sr parameter for MFA challenges if you have that configured.

cd /usr/local/openvpn_as/scripts
./authcli -u "test"

You can find any information that the post-auth script outputs in the /var/log/openvpnas.log file (by default). You can also edit the pas_only.py file on your server and add 'print' lines to it to dump more information into the log file to try and see what values are in particular variables as Access Server processes the post-auth file.

You can easily filter for specific messages from post-auth with these commands:

cat /var/log/openvpnas.log | grep "POST_AUTH"