OpenVPN Access Server post_auth LDAP group mapping script

Authentication and role of post_auth

The post_auth programming hook in Access Server was put in to extend the possibilities of the Access Server to authenticate against a source of credentials. By default without using post_auth the following sources can be authenticated against in Access Server:

    This method relies on using an SQLite3 database that is stored on the Access Server’s file system itself. It contains both the user properties and the user credentials. Management of credentials is handled in the ‘user permissions’ area of the admin web services of the Access Server.
  • PAM
    This is the system that is present on Linux systems, and is the default choice for the Access Server. This uses the credentials from the Linux system itself to authenticate to. Management of credentials is done in the console/SSH session in the Linux OS itself using standard tools like adduser, deluser, and passwd.
  • LDAP
    To connect to an OpenLDAP or Windows AD, the LDAP option is fairly easy to use. For security a proxy account can be made on the LDAP server through which the Access Server can talk to the LDAP server to perform authentication against the credentials stored in the LDAP server. Management of credentials is handled by using LDAP browsing and management tools, or in Windows AD by using the “Active Directory Users and Computers” program.
    Like LDAP, the credentials are stored in the RADIUS server, and management of credentials is handled by using the tools available for browsing and manipulating the contents of the RADIUS credentials database. Windows Server Active Directory supports the ability to allow the Access Server to query the AD over the RADIUS protocol, as is the case with LDAP.

The post_auth script is run during the authentication session where a user tries to log in at the Access Server from a compatible OpenVPN client or on the web interface. In this post_auth script both cases are relevant. The script runs just after the authentication phase has succeeded. Hence, post_auth – after authentication. The script itself is a text file in the programming language Python. With it you can do all sorts of interesting things like adding an extra filter to the login process, or implementing a custom authentication system, or in this case to automate assigning users to groups based on certain criteria.

This script is intended to be used only for LDAP authentication, and can read the 'memberOf' property from the LDAP server to determine what Access Server group to place a user in automatically. This does require that your LDAP server supports the 'memberOf' property and has it enabled. Windows Server platforms with an LDAP connector to Active Directory generally has this enabled by default already. OpenLDAP is capable of supporting this as well but usually requires a configuration change before it starts reporting this property.

Note that if you only need to assign a few users to groups, a manageable amount, then you can also choose to do this without this script and just manually add the user by its login name to the ‘user permissions’ panel in the Access Server, and then assign that user to a group in Access Server. Note that case sensitivity is important here. The login name as stored in the LDAP server is leading here. So for example if the user is known as Billy.Bob in the LDAP server, then that user name must also be used in the 'user permissions' panel in Access Server when you want to assign this user to a specific group.

From a user perspective

When the user logs in, Access Server will look up the user in the 'user permissions' panel, and if there is a match, it will apply the properties you have set on this user. For example if you have assigned the user to a specific group, then the user will inherit access control rules and other properties from that group. But it can be impractical to manually add all your users that exist in your LDAP server to Access Server for access control purposes. So this step of assigning a user to a group in Access Server can be automated with this post-auth script for LDAP group mapping. It will use the 'memberOf' property to determine what group to place the user in.

To put the process that the post_auth script goes through into a simpler view:

  • User logs in through web services or through OpenVPN client software
  • Access Server contacts the LDAP server and asks if the username/password is correct.
  • LDAP server responds with positive answer.
  • Access Server sees positive response, runs post_auth script.
  • post_auth script checks with the LDAP server to see what LDAP group that user has (memberOf property).
  • post_auth script uses specified rules to match LDAP group name to AS group name.
  • post_auth script assigns the user to the specified group in Access Server and saves it.
  • User connects with properties inherited from that Access Server group.

How to install/update the script

In our documentation we are assuming you have logged on through SSH or the console of your server running the OpenVPN Access Server and that you have obtained root privileges. The script itself is available from our website at the URL mentioned below, the script file itself has to be saved 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 and that it is stored in the following folder: /root/

It could be retrieved directly on your server as root user like so:

wget -O /root/

Note that 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 that is done 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/ ConfigPut
./sacli start

If you make alterations to the file then you will need to use the above commands again to load the new version of the script into the configuration database, and to reload the configuration of the Access Server again.

Read on to learn what you should change in the script to make the script map your LDAP groups to Access Server groups.

Mapping LDAP groups to Access Server groups

You will need to edit the script and use the provided examples to map specific LDAP group membership names to their Access Server counterpart groups. This will make it so that if a user logs in at the Access Server, and the LDAP server approves the credentials, the post_auth script will read the ‘memberOf’ attribute to see what LDAP groups that user is a part of. This group information is then held against a list you have programmed into the post_auth script itself, and uses these rules to assign the user to a specific Access Server group. The user will then inherit the properties that are assigned to that Access Server group. These properties can determine to which subnets the user has access, for example. This does require that you set up groups in Access Server to map to.

It is important to note that group names in LDAP do not have to be the same as group names in the Access Server. The script can for example look for a group name titled “VPN Users” in the LDAP directory, but assign it to a group titled “Limited Access” in the Access Server.

Open the file in a text editor like for example nano:

nano /root/

Now go down to the section that looks like this:

# determine the access server group based on LDAP group settings
if 'Administrators' in ldap_groups:
group = "admin"
elif 'Sales' in ldap_groups:
group = "sales"
elif 'Finance' in ldap_groups:
group = "finance"
elif 'Engineering' in ldap_groups:
group = "engineering"

That section of code shown above is the part in the LDAP post_auth group mapping script that you need to change to assign LDAP groups to groups in the Access Server. The rest of the code should be left intact. In the code you can see:

if 'Administrators' in ldap_groups:

This looks for the phrase “Administrators” in the LDAP group name(s) that were passed to the post_auth script by the LDAP server for the user that is currently logging in. If the user is part of the group called "Administrators", then it will run the following code to assign the user to the Access Server group “admin”:

group = "admin"

The other lines underneath all check for different LDAP group names and assign to other groups. Feel free to edit this. If there are too many, simply remove some. If you need more groups, then simply copy and paste the two lines that start with “elif” and “group” to expand the list of group matching criteria. After you are done, you can press ctrl+x to exit the nano text editor and you can save the file.

Once that is done 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/ ConfigPut
./sacli start

Default group mapping behavior

OpenVPN Access Server has an option in the Admin UI under Group Permissions where you can define a default group. A default group is where users will be placed implicitly if they are not yet a member of a group already. If you are using this option, you should also update the default group definition in the LDAP group mapping script. The post_auth group mapping script also has a default group setting, and it will override what you set in the Admin UI.

When the script queries the LDAP server for group membership information it can return with an error or no information at all. Almost certainly this will mean that the user is simply not a part of a group in the LDAP directory at all. With the setting below, you can define a default group that the user should be a part of should this be the case. By default this script will set it to an empty string, which means the user will be removed from any group. This is the section in the script where this behavior can be altered:

# Default group assignment - update this if you use the default group setting in Access Server.
group = ""

How to uninstall the script

The script is loaded into the configuration database, and can be removed from there with the following commands. Note that this action does not remove the group assignments already saved in the database, but you can clear those up in the Admin UI or via the command line utilities if you want to.

To uninstall/remove a post_auth script:

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

How to debug any problems

There is a tool called authcli in the /usr/local/openvpn_as/scripts/ folder than can help to debug authentication sessions from the command line, and it provides information about what user properties are actually being applied. You can for example run the following command to see what properties are set for the user "test". The output that will be shown afterwards should include any parameters that the post_auth script adds to the user. You can additionally add -sr parameter to provide a response to a multifactor authentication challenge, should you have one.

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

Any information that the post_auth script outputs to the log file can be found in the /var/log/openvpnas.log file (by default) on most Access Server setups. You can also edit the file you have 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 process 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"