Tutorial: Create a Custom Authentication System with a Python Script
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.
For more about post_auth scripts, refer to the plugins documentation topic.
Installed Access Server.
A basic Python language understanding.
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.
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 — 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.
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
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.pyOpen the file and edit the code for your specific script.
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
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 systemctl restart openvpnas
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.
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 systemctl restart openvpnas
If you use custom authentication with a cluster of Access Servers, ensure the following:
Each node is on Access Server 2.11.1 or newer.
Load and enable PAS-only authentication on all nodes.
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"