OPENVPN CLOUD IS LIVE: TRY TODAY FOR FREE

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:

  • LOCAL
    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.
  • RADIUS
    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 ldap.py and that it is stored in the following folder: /root/ldap.py

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

wget https://swupdate.openvpn.net/scripts/post_auth_ldap_autologin_dbsave.py -O /root/ldap.py

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/ldap.py ConfigPut
./sacli start

If you make alterations to the ldap.py 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 ldap.py 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 ldap.py 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 ldap.py file in a text editor like for example nano:

nano /root/ldap.py

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/ldap.py ConfigPut
./sacli start

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 MAC addresses already saved in the database, but these will simply be ignored and not cause further issues. It is possible to clean those up manually if you wish with the sacli command, and instructions are provided for that in the next section.

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.

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 ldap.py 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"

 

Share