Skip to main content

Tutorial: How to Set Up SAML Group Mapping with a Post-auth Script

Abstract

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.

Prerequisites

  • An installed Access Server 2.11.1 or newer.

  • An identity provider (IdP).

Step 1: Enable SAML authentication

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

Step 2: 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 Advanced Options, then check Customize the name of the group claim, and enter groups.

  7. Click Save.

Important

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.

Important

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

Important

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

Step 3: 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.

  1. Sign in at the Access Server (SSH or console) with root privileges.

  2. Download and save the Python script to a location on your Access Server.

    • Python script URL: https://swupdate.openvpn.net/scripts/post_auth_saml_group_mapping.py

    • You can retrieve the script 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.py1

      1

      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.

Step 4: Edit the script

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

    nano /root/saml.py

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

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

Step 5: Load the script and soft reload the Access Server service

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

Step 6: 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...
In this section:
See also: