Tutorial: How to Set Up SAML Group Mapping with a Post-Auth Script
Automate SAML group mapping with a post-authentication script loaded on your Access Server.
Overview
With SAML authentication, users can connect to your Access Server with their SAML credentials and get access to 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. Normally, the server administrator assigns users to groups, but you can automate group assignments.
After successful authentication, the Access Server can run a post-auth (post-authentication) script written in Python3 to perform additional tasks. We provide a post-auth script that reads a SAML group membership attribute sent by the IdP and uses that to automatically assign the user to a group in Access Server. Ensure you define these group mappings in the post-auth script and configure the SAML IdP to send the group information to the Access Server in the SAML assertion.
To enable SAML group mapping using a script, follow these tutorial steps.
An installed Access Server 2.11.1 or newer.
An identity provider (IdP).
To start, ensure you enable SAML authentication with your IdP. We provide guides for some providers.
From your IdP admin console, you can configure group mapping. Here are some tips for some providers.
Microsoft Azure AD
Sign in to your Microsoft Azure Portal.
Click Enterprise Applications and select the SAML application.
Click Single Sign On configuration, then User Attributes & Claims.
Click Add a group claim.
Click All groups and set Group ID as the Source attribute.
Click Advanced Options, then check Customize the name of the group claim, and enter groups.
Click Save.
Important
Use the Azure Group Object ID as the SAML group name.
Google Workspace
Sign in to your Google Workspace Admin Console.
Click Apps, then Web and mobile apps, then the SAML application.
Click SAML attribute mapping.
In Group membership (optional), add your Google groups.
In App attribute, enter groups, then click Save.
OneLogin
Sign in to your OneLogin administration portal.
Click Applications, Applications, and select the SAML application.
Click Parameters, then the + sign to add a new field.
In Field name, enter groups.
Check Include in SAML assertion, then click Save.
Set Value to Department, then click Save.
Important
The department name is the group name.
Keycloak
Sign in to your Keycloak administration portal.
Click Clients and select your SAML application.
Click the Mappers tab and create a new mapper.
Set your own descriptive name in the Name field.
Set Mapper Type to Group list.
Set Group attribute name to groups.
Set Single Group Attribute to ON and Full group path to OFF.
Click Save.
Okta
Sign in to your Okta administration portal.
Click Directory > Profile Editor.
Click on the profile for your SAML application user account.
Under Attributes, click Add Attribute.
The Add Attribute window pops up.
Set Display name to "Groups" and Variable name to "groups."
Click Save.
Click Applications, Applications, and select your SAML application.
Click the General tab, then click Edit in SAML Settings.
Under Group Attribute Statements (optional), click Add another.
Set Name to groups, and set Filter to Matches regex: .*
Click Save.
Click your SAML application again and then click Assignments.
Click Assign, select Assign to Groups, and click Save.
JumpCloud
Sign into the JumpCloud administration portal.
Click SSO and select your SAML application.
Click the SSO tab, and scroll down to Group Attributes.
Check Include group attribute and set it to groups.
Click Save.
In User Groups, select your JumpCloud groups.
On the Applications tab, check the box for your SAML app.
On the Directories tab, select the directory you need enabled.
Click Save.
Important
The attribute we’re using to report the group name to Access Server is groups, and it’s case-sensitive.
After you've configured and enabled the group name information in the SAML IdP, assertions returned to the Access Server now contain the group information. If you followed the above instructions, this should be the groups attribute, and the post-auth SAML group mapping script can read that information.
Sign in at the Access Server (SSH or console) with root privileges.
Download and save the Python script to a location on your Access Server.
Python script URL: https://packages.openvpn.net/as/scripts/post_auth_saml_group_mapping.py
You can retrieve the script directly on your server using wget as the root user:
wget https://packages.openvpn.net/as/scripts/post_auth_saml_group_mapping.py -O /root/saml.py1
This saves the script to the root/ directory with the name saml.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 saml.py file in a text editor (for example, nano):
nano /root/saml.py
Go down to the section that looks like this:
# Adjust these to map the user's SAML group membership to an Access Server group. def determine_group(saml_groups): group = None if 'Administrators' in saml_groups: group = "admin" elif 'Sales' in saml_groups: group = "sales" elif 'Finance' in saml_groups: group = "finance" elif 'Engineering' in saml_groups: group = "engineering" return groupUpdate the script to assign SAML groups (IdP) to Access Server groups.
That section of code shown above is the part in the SAML post-auth group mapping script that you must change to assign SAML groups to groups in the Access Server. The rest of the code should be left intact. In the code, you can see the following:
if 'Administrators' in saml_groups:
This looks for the phrase “Administrators” in the SAML group name(s) passed to the post-auth script by the SAML IdP for the user currently logging in. If the user is part of the group called “Administrators”, then it runs the following code to assign the user to the Access Server group “admin”:
group = “admin”
The other lines underneath check for different SAML group names and assign them to other groups. Feel free to edit this. If there are too many, remove some. If you need more groups, copy and paste the two lines that start with “elif” and “group” to expand the list of group matching criteria. After you’re done, you can press ctrl+x to exit the nano text editor, and you can save the file.
Once you’re ready, you can load the script and reload Access Server:
cd /usr/local/openvpn_as/scripts ./sacli --key "auth.module.post_auth_script" --value_file=/root/saml.py ConfigPut ./sacli start
Each time you make changes to the saml.py file, you must use the above commands to load the new version of the script into the configuration database and reload the Access Server configuration.
We recommend testing with users with different group assignments. You can sign in at the Access Server web interface and check the log file /var/log/openvpnas.log on the server. Here are some samples of output from the post-auth script:
If you’ve configured everything correctly, you’ll see a successful group mapping:
POST_AUTH: User group mapping found for 'lauren@helloworld.com', setting OpenVPN connection group to 'YourGroup' ...
In case your SAML IdP is not configured correctly, you’ll see this:
POST_AUTH: Groups for user lauren@helloworld.com are not reported, please check your IdP configuration
In case the SAML group is reported, but there’s no mapping for it:
POST_AUTH: No group mapping matches found for 'lauren@helloworld.com' ... Using default group settings...