Access Server post-auth SAML group mapping script

Introduction

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 language 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 assign the user to a group in Access Server automatically. 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 the steps detailed below:

1. Configure and enable SAML authentication.
2. Configure the IdP to send the group information.
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.

Note: Ensure you are running Access Server 2.11.1 or newer.

Enable SAML authentication

To start, ensure you enable SAML authentication with your IdP. We provide guides for some providers:

• How to configure SAML with Azure AD.
• How to configure SAML with Google Workspace.
• How to configure SAML with OneLogin.
• How to configure SAML with Keycloak.
• How to configure SAML with Okta.
• How to configure SAML with JumpCloud.

Configure group mapping with your IdP

From the admin console of your IdP, you can configure group mapping. Here are some tips for some providers.

Microsoft Azure AD

1. Sign in to your Microsoft Azure Portal.
2. Click Enterprise Applications and select the SAML application.
3. Click Single Sign On configuration, then User Attributes & Claims.
4. Click Add a group claim.
5. Click All groups and set Group ID as the Source attribute.
6. Click on Advanced Options, then check Customize the name of the group claim, and enter groups.
7. Click Save.

Note: Use the Azure Group Object ID as the SAML group name.

Google Workspace

1. Sign in to your Google Workspace Admin Console.
2. Click Apps, then Web and mobile apps, then the SAML application.
3. Click SAML attribute mapping.
4. In Group membership (optional) add your Google groups.
5. In App attribute, enter groups, then click Save.

OneLogin

1. Sign in to your OneLogin administration portal.
2. Click Applications, Applications, and select the SAML application.
3. Click Parameters, then the + sign to add a new field.
4. In Field name, enter groups.
5. Check Include in SAML assertion, then click Save.
6. Set Value to Department, then click Save.

Note: The department name is the group name.

Keycloak

1. Sign in to your Keycloak administration portal.
2. Click Clients and select your SAML application.
3. Click the Mappers tab and create a new mapper.
4. Set your own descriptive name in the Name field.
5. Set Mapper Type to Group list.
6. Set Group attribute name to groups.
7. Set Single Group Attribute to ON and Full group path to OFF.
8. Click Save.

Okta

1. Sign in to your Okta administration portal.
2. Click Directory, Profile Editor, then Profile on your SAML application.
3. Under Attributes, click Add Attribute.
4. Add the new attribute called groups, and click Save.
5. Click Applications, Applications, and select your SAML application.
6. Click the General tab, then click Edit in SAML Settings.
7. Under Group Attribute Statements (optional), click Add another.
8. Set Name to groups, and set Filter to Matches regex: .*
9. Click Save.
10. Click your SAML application again and then click Assignments.
11. Click Assign, select Assign to Groups, and click Save.

JumpCloud

1. Sign into the JumpCloud administration portal.
2. Click SSO and select your SAML application.
3. Click the SSO tab, and scroll down to Group Attributes.
4. Check Include group attribute and set it to groups.
5. Click Save.
6. In User Groups, select your JumpCloud groups.
7. On the Applications tab, check the box for your SAML app.
8. On the Directories tab, select the directory you need enabled.
9. Click Save.

Note: The attribute we’re using to report the group name to Access Server is groups, and it’s case-sensitive.

Customize the post-auth script

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.

Provide the post-auth script with a list of mappings from SAML IdP group names to Access Server group names by editing the sample script we’ve provided and loading it into the Access Server.

1. Login at the Access Server (SSH or console) with root privileges.
2. Download and save the script on the Access Server.
3. Edit the script to alter the group mappings in the script.
4. Load the script into Access Server and reload.
5. Test user login.

Sign in to your Access Server

Ensure you sign in with root privileges to run the commands in the following steps.

Download the post-auth script

Download and save this Python script to a location on your Access Server:

• https://swupdate.openvpn.net/scripts/post_auth_saml_group_mapping.py

You can retrieve it directly on your server using wget as the root user:

wget https://swupdate.openvpn.net/scripts/post_auth_saml_group_mapping.py -O /root/saml.py

Note: If you encounter issues downloading the script, you may need to install or update wget or ca-certificates.

Edit the script

Open the saml.py file in a text editor (for example, nano):

nano /root/saml.py

Now 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 group

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.

Load script and soft reload

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.

Test user login

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