Skip to main content

Tutorial: Create a Custom Authentication System with a Python Script

Abstract

You can set up a custom authentication method for Access Server using a Python3 script. Here we provide you with information on how to do it.

Overview

Access Server’s post-auth script (PAS) supports setting up a custom authentication method. Using a PAS in Python3 language, you can extend Access Server’s built-in authentication methods. 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 called 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 user.

Important

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

For more about post_auth scripts, refer to the plugins documentation topic.

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 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 Access Server program.

Prerequisites

  • Installed Access Server.

  • A basic Python language understanding.

Step 1: Understand how the PAS-only script works

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.

Important

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:

  1. RETAIN_PASSWORD=true — credentials entered by the user are made available to the script.

  2. AUTH_NULL=true — bypasses Access Server authentication for PAS-only users and lets 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. Users authenticated against PAS-only authentication pass their credentials transparently through Access Server to the post-auth script responsible for approving or denying their authentication request.

Step 2: Install and update the script

In our documentation, we assume you’re logged on through SSH or the console of your server running the 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://packages.openvpn.net/as/scripts/post_auth_pas_only.py

  1. Retrieve the file directly on your server as root user with this command:

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

  2. Open the file and edit the code for your specific script.

  3. 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

Tip

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.

Step 3: Active and use 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

Enable PAS-only authentication as the default authentication method or for specific users or groups:

  • Sign in to the Admin Web UI and enable PAS-only authentication as the default, for a group, or for a user:

    • Enable PAS-only as default: Click Authentication > Settings, select PAS only as the default authentication, and save settings.

    • 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.

    • 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.

Optional: 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

Optional: 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.

Important

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

Debug tips

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. If you have that configured, you can add the -sr parameter for MFA challenges.

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"
In this section:
See also: