Tutorial: How to Set Up LDAP Group Mapping with a Post-auth Script
Using a custom Python script to automate group mapping with LDAP authentication.
Overview
With Lightweight Directory Access Protocol (LDAP), users can connect to your Access Server with their LDAP credentials and access resources. You can configure the access control rules to grant access globally for all users or on a per-user and per-group basis. Typically, the server administrator manually assigns users to groups, but you can automate group assignments.
After successful authentication, the Access Server can run a post-auth (post-authentication) Python3 script to perform additional tasks. We provide a post-auth script that reads an LDAP group membership attribute supplied by the LDAP server and uses that to assign the user to a group in Access Server automatically.
Ensure you define these group mappings in the post-auth script and configure the LDAP server to provide the group membership attribute to the Access Server.
To enable LDAP group mapping using a script, follow the steps detailed below:
Configure and enable LDAP authentication.
Configure the LDAP server to provide group membership.
Customize the post-auth script to set up the group mappings.
Install the post-auth script into the Access Server.
The test user signs in and confirms functionality.
An installed Access Server.
A directory with LDAP.
To start, ensure you enable LDAP authentication. We provide guides for some LDAP servers:
After you enable LDAP authentication for users, create your groups in Access Server:
Sign in to the Admin Web UI.
Click User Management > Group Permissions.
Enter your group names, configure their settings, and save.
Tip
For more about the Group Permissions in the Admin Web UI, refer to Group Permissions — Access Server Admin Web UI User Manual.
Once you've configured Access Server to authenticate against your LDAP server, you can customize the LDAP group mapping. The script does the following:
Runs after successful user authentication with credentials before Access Server allows the connection.
Read the 'memberOf' property from the LDAP server.
Matches the 'memberOf' property to an Access Server group.
Puts the user into that Access Server group.
Is case sensitive — handles the user, john, differently than the user, John.
Important
Your LDAP server must support the 'memberOf' property, and you must enable it. Windows Server platforms with an LDAP connector to Active Directory typically have this enabled by default. OpenLDAP can support it but typically requires a configuration change to report the property.
Sign in to your Access Server console with root privileges.
Download the sample post-auth script:
wget https://swupdate.openvpn.net/scripts/post_auth_ldap_autologin_dbsave.py -O /root/ldap.py
Tip
The script itself is available at the URL below. You must save the script file to your Access Server, as done with the wget command above. Your file name isn't important, but for our example, we use ldap.py and store it in the directory /root/. https://swupdate.openvpn.net/scripts/post_auth_ldap_autologin_dbsave.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.
Now you must customize the script with the following:
The names of your LDAP groups.
The names of your Access Server groups.
Tip
The group names in LDAP don't have to be the same as those in Access Server. For example, you can assign a "VPN users" group in the LDAP directory to a "Limited Access" group in Access Server.
Connect to your console with root privileges.
Open the ldap.py file in a text editor (we use nano for our command):
nano /root/ldap.py
Scroll down to this section:
# 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"
Edit that code section using the guidelines below, creating your specific mappings. (The post-auth script looks for the ldap_groups name listed in the LDAP group name(s) sent by the LDAP server to the post-auth script for the authenticating user. If the user belongs to the specific LDAP group, the script assigns the user to the Access Server group that follows.)
LDAP server group
Access Server group
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"
If there are too many group mapping lines in the script, delete the extra lines.
If you need more group mapping lines, enter two new lines for each group mapping, starting with "elif" and "group."
After editing, exit the nano text editor with ctrl+x and save the file.
Reload the script and restart the Access Server service:
cd /usr/local/openvpn_as/scripts ./sacli -k auth.module.post_auth_script --value_file=/root/ldap.py ConfigPut ./sacli start
Note
If a user is a member of the Engineering LDAP group, the script assigns them to the engineering Access Server group. Suppose you have a user in both the Administrators and Engineering groups. In that case, the script assigns the user to the first group sent from the LDAP server.
You have the option of defining a default group in Access Server. When you set a default group, users you haven't explicitly assigned to groups get assigned to the default group.
If you set a default group, you must update the default group definition in the LDAP group mapping script.
Set a default group and update the post-auth script:
Sign in to the Admin Web UI.
Click User Management > Group Permissions.
Select your desired group from the drop-down list for Default Group Permissions to use for any User not in any Group.
Connect to the Access Server console with root privileges.
Open the post-auth script for editing:
nano /root/ldap.py
Scroll down and edit the post-auth script's default group assignment:
# Default group assignment - update this if you use the default group setting in Access Server. group = ""
Reload the script and restart the Access Server service:
cd /usr/local/openvpn_as/scripts ./sacli -k auth.module.post_auth_script --value_file=/root/ldap.py ConfigPut ./sacli start
Note
Suppose you have a user who isn't assigned to an LDAP group and you don't have a default group assigned in the script. If so, the script sets the user's groups to an empty string.
Here's the process for a user connecting from OpenVPN Connect:
The user signs in on OpenVPN Connect, sending their credentials to Access Server.
Access Server sends the user credentials to authenticate with the LDAP server.
The LDAP server responds that authentication passes.
Access Server runs the post-auth script.
The post-auth script checks with the LDAP server for group membership.
The LDAP server sends the group name, and the post-auth script matches the Access Server group.
The post-auth script assigns the user to the Access Server group.
Now that the user has an Access Server group, they inherit the group properties the next time they make a VPN connection.
Note
Users follow a similar process when signing into the Client Web UI.
Troubleshoot authentication with authcli tool
You can use the authcli tool in the /usr/local/openvpn_as/scripts/ folder to help debug authentication sessions from the command line. The authcli tool provides information about what user properties are applied.
For example, you can run a test to see the properties for the user "test". The output shown includes any parameters the post-auth script adds to the user.
cd /usr/local/openvpn_as/scripts ./authcli -u "test"
Tip
If you need to test with a multi-factor authentication setup, use the -sr parameter to provide the MFA challenge response.
Review the log files
The post-auth script saves information to the log file: /var/log/openvpnas.log. This is the default log file name and location for Access Server.
Add print lines to the script
You can edit the ldap.py file on your server and add 'print' lines to dump more information into the log file. This can help you see the values in particular variables as the Access Server processes the post-auth file.
Filter for post-auth messages
You can filter the log file to display only messages from post-auth with this command:
egrep "POST_AUTH" /var/log/openvpnas.log