OpenVPN Access Server post_auth LDAP group mapping script

Introduction

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 for granting access to apply 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:

1. Configure and enable LDAP authentication.
2. Configure the LDAP server to provide group membership.
3. Customize the post_auth script to set up the group mappings.
4. Install the post_auth script into the Access Server.
5. Test user login and confirm functionality.

Enable LDAP authentication

To start, ensure you enable LDAP authentication. We provide guides for some LDAP servers:

• How to configure LDAP with Active Directory.
• How to configure LDAP with Google Workspace.
• How to configure LDAP with Okta.
• How to configure LDAP with JumpCloud.

Configure Access Server groups

After you enable LDAP authentication for users, create your groups in Access Server:

1. Sign in to the Admin Web UI.
2. Click User Management > Group Permissions.
3. Enter your group names, configure their settings, and save.

For more about the Group Permissions in the Admin Web UI, refer to Group Permissions — Access Server Admin Web UI User Manual.

Download the post-auth Python script

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.

Note: 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.

Begin by downloading the post-auth sample script:

1. Sign on to your Access Server via SSH and obtain root privileges.
2. Download the script:
   

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

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

Edit the script to map LDAP groups to Access Server groups

Now you must customize the script with the following:

1. The names of your LDAP groups.
2. The names of your Access Server groups.

Note: 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.

To edit your script:

1. Signed into the server via SSH with root privileges.
2. Open the ldap.py file in a text editor (we use nano for our command):
   

   nano /root/ldap.py

3. 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"
   

4. 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"

5. If there are too many group mapping lines in the script, delete the extra lines.
6. If you need more group mapping lines, enter two new lines for each group mapping, starting with "elif" and "group."
7. After editing, exit the nano text editor with ctrl+x and save the file.
8. Reload the script:
   

   cd /usr/local/openvpn_as/scripts
   ./sacli -k auth.module.post_auth_script --value_file=/root/ldap.py ConfigPut
   ./sacli start

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.

Behavior for the default group (optional)

You have the option of defining a default group in Access Server. You set this in the Admin Web UI on the User Management > Group Permissions page. When you set a default group, users you haven't explicitly assigned to groups get assigned to the default group.

If you use this option for your Access Server, ensure you update the default group definition in the LDAP group mapping script. To do this, you 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 = ""

Suppose you have a user that 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 as an empty string.

Load the script

After making your changes to the script, load it into your Access Server configuration and restart Access Server:

cd /usr/local/openvpn_as/scripts
./sacli -k auth.module.post_auth_script --value_file=/root/ldap.py ConfigPut
./sacli start

Your users should now be able to connect with LDAP authentication and be assigned to a group automatically.

LDAP group mapping post-auth user flow

Here's the process for a user connecting from OpenVPN Connect. 

1. The user signs in on OpenVPN Connect, sending their credentials to Access Server.
2. Access Server sends the user credentials to authenticate with the LDAP server.
3. The LDAP server responds that authentication passes.
4. Access Server runs the post-auth script.
5. The post-auth script checks with the LDAP server for group membership.
6. The LDAP server sends the group name, and the post-auth script matches the Access Server group.
7. The post-auth script assigns the user to the Access Server group.
8. 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.

Uninstall the script (if necessary)

If you need to uninstall the script from your Access Server, use the commands below. When you run these commands, the script is removed from the configuration database. This action doesn't remove the group assignments already saved in the database.

To uninstall the post-auth script:

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

Troubleshooting tips

Here are some tips to help if you encounter trouble.

Can't install the script

If you have problems downloading the script with the wget command, you may need to install or update the wget and ca-certificates packages on your system.

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"

Note: 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:

cat /var/log/openvpnas.log | grep "POST_AUTH"