Tutorial: How to Set Up Hardware Address Checking with a Post-auth Script⁠

Overview⁠

The post-auth programming hook in Access Server allows you to extend the server's possibilities for authenticating against a source of credentials. This document provides examples for creating a post-auth script that includes the hardware address as part of the authentication process.

Authentication and the post-auth script role⁠

Access Server's authentication system⁠

Access Server supports several robust authentication systems without using a post-auth script — whether you manage it from the Admin Web UI or authenticate against a third-party system. These are the systems already supported:

Local: Access Server's built-in authentication system storing user credential hashes in the user properties database, with management handled in the Admin Web UI.
PAM: Linux system that requires console management or an SSH session on the OS.
LDAP: Once you set up the connection in the Admin Web UI, Access Server can authenticate against an LDAP server.
RADIUS: Once you set up the connection in the Admin Web UI, the Access Server can authenticate against a RADIUS server.
SAML: Once you set up the connection in the Admin Web UI, Access Server can use SAML single sign-on (SSO) by authenticating through an identity provider (IdP).

For more information about these authentication methods, refer to this detailed topic: Authentication System.

The post-auth script process⁠

The user signs in with a VPN client or on the Client Web UI.
They successfully authenticate with their credentials.
The post-auth script runs (hence, post-auth — after authentication).

The post-auth script is a text file written in Python. It can do all sorts of interesting things, like automating user group assignment based on specific criteria, implementing a custom authentication system, adding an extra filter to the login process, or checking the user device's hardware address.

Prerequisites⁠

An installed Access Server.
Python script knowledge.
Root access on the server.

You can create a hardware address checking script to enhance the security of your authentication by only allowing users with registered MAC addresses and UUID strings to connect to the VPN server successfully.

Our sample script automatically registers the device’s MAC address or UUID string, but you can configure it to have complete control over it as the administrator. The post-auth script can accept two hardware addresses per account, but only auto-registers the first; you can manually add the optional secondary address.

From a user perspective⁠

When a new user signs in and you’re using the default settings for our post-auth script, here’s the process:

A new user signs in with valid credentials.
The MAC or UUID isn’t in your Access Server’s user properties database.
Access Server automatically registers and stores the MAC or UUID in the user properties database.
The next time the user signs in, their MAC or UUID must match the value stored in the user properties database.

Users can use most open-source clients or recent versions of OpenVPN Connect for this authentication. See below for more detailed information about client compatibility. Older clients don’t provide a MAC address or UUID string, which will lead to an error message when a user tries to connect.

Connection profile and client compatibility notes⁠

About connection profiles: This script works with all three types of connection profiles: user-locked, server-locked, and auto-login. All adhere to the restrictions in this post-auth script. In some cases—such as with the auto-login connection profile—OpenVPN Connect may end up looping endlessly trying to connect when it‘s denied access based on MAC address or UUID string restriction, in which case you need to correct the situation by making sure the correct hardware address is registered for your device.

About client software: We recommend using OpenVPN Connect v3, however recent versions of OpenVPN Connect v2 (2.7.* and newer) are supported. This script works with OpenVPN Connect for Windows, macOS, iOS, and Android. We've also tested the following clients, but don't guarantee support by us:

The open-source client 'openvpn' on Linux.
The open-source client 'OpenVPN GUI' on Windows.
The open-source client 'Tunnelblick' on macOS.
Most open-source clients based on 'openvpn' binary version 2 or version 3 should work.

Sign in through SSH or your Access Server server console.
Obtain root privileges.
Retrieve the example Python script from our website (https://packages.openvpn.net/as/scripts/post_auth_mac_address_checking.py):
```
wget https://packages.openvpn.net/as/scripts/post_auth_mac_address_checking.py -O /root/mac.py
```
1. This saves the script to the /root/directory with the name mac.py.
Tip⁠
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.
Edit the script for your specific needs:
```
nano /root/mac.py
```
- Make your changes to the script, then save and exit.

Load the script into the Access Server configuration and reload Access Server:

sacli --key "auth.module.post_auth_script" --value_file=/root/mac.py ConfigPut
sacli start

Register a user's hardware address manually. For our command, "exampleuser" is the user account name, and the client's UUID is 6A13F222-53F2-EA22-873F-A4AE122AAB22.

sacli --user "exampleuser" --key "pvt_hw_addr" --value "6A13F222-53F2-EA22-873F-A4AE122AAB22" UserPropPut
sacli start

If the user account is being used on another device or the hardware address has changed, you must remove the MAC address or UUID string stored and locked for that particular user. You can use the following commands to remove the saved value for the user "exampleuser" and reload the server.

Remove saved MAC address or UUID string for exampleuser:

sacli --user "exampleuser" --key "pvt_hw_addr" UserPropDel

There are use cases requiring a secondary hardware address. For example, a laptop may report a different MAC address, whether it connects over wifi or an ethernet connection.

You can manually specify a secondary address accepted for a user account. This assumes a MAC address or UUID string is already present in the user database for a specific user. You can simply add a secondary address that’s also accepted. We don’t allow automatic registration for the secondary address for security reasons.

Manually register/update a secondary MAC address or UUID string for exampleuser:

sacli --user "exampleuser" --key "pvt_hw_addr2" --value "ef:cd:ba:03:02:01" UserPropPut

Remove network restrictions⁠

If you use the restriction to allow only hardware address registrations from a specific IP address, as explained above, then you should remove that restriction when troubleshooting:

Undo that particular restriction in your mac.py file.
Install/update the post-auth script again.
Reload the settings again.
Test your connections.

That way, that restriction won't be an issue when debugging why things aren't working.

Use the latest software versions⁠

Ensure you use the latest software, as older software may not support reporting MAC addresses or UUID strings to the server. That goes for the client and server software, as running old server software is also not a good idea.

Check log files⁠

On most Access Server setups, you can find any information the post_auth script outputs to the log file in the /var/log/openvpnas.log file (by default). You can also edit the mac.py file on your server and add 'print' lines to it to dump more information into the log file and see what values are in particular variables as Access Server processes the post_auth file.

Filter for specific messages from post-auth:
```
egrep "POST_AUTH" /var/log/openvpnas.log
```

Can't find what you're looking for?

Our support team will be happy to assist you.

Contact Support Schedule a Demo