Resources > Configuring Single Sign-On via Entra in LISTSERV

LISTSERV Tech Tip

Q: How can I configure single sign-on via Entra in LISTSERV?

By Xinlu Shen
Software Support Engineer, L-Soft

LISTSERV 17.5 comes with support for SAML single sign-on through an extension to LISTSERV that needs to be installed separately. In this tech tip, we'll walk you through the procedure of adding Entra to the LISTSERV web interface as a SAML single sign-on provider.

LISTSERV 17.5 Login: When Entra SSO is active, you'll see "Single Sign-On (Entra)" below the login fields, confirming that your setup is complete and ready for users.

Prerequisites

LISTSERV 17.5
Microsoft Entra (Cloud Application Administrator or Application Administrator role required)
The LISTSERV SAML Application

(If you are a ListPlex cloud hosting customer, contact L-Soft hosting support to assist you with the SAML setup. You will be provided with an SP Metadata URL, which you will need to download, after which you can go to the next section to create an enterprise application in Entra.)

This tech tip assumes that you already have the LISTSERV SAML extension installed and properly initialized. When this is done, your samlsettings.json configuration file, which can be found in the SAML folder, should look something like this:

{
  "WaUrl": "https://listserv.example.com/scripts/WA.EXE",
  "ServiceUrl": "https://listserv.example.com/sso",
  "IdpProfiles": [],
  "EnableSetupPage": true
}

With a correct initial setup, the setup page should load with information in JSON format that identifies your site and can help with your IdP configuration. In the rest of this tech tip, we'll show how to create an application in Entra and integrate it with the LISTSERV SAML extension.

Creating an Enterprise Application in Entra

After signing in to the Microsoft Entra admin center, go to "Identity > Applications > Enterprise applications". From "Manage > All applications", click on "New application".

Then click on "Create your own application" and type in the name of this app.

You will see this app getting created, and it will show you the dashboard of the app. Assign users and group access to this app as needed.

Next, go to "Manage > Single sign-on", and select SAML as the single sign-on method.

This will bring you to a screen where all the SAML details of this app can be seen and configured.

Click on "Upload metadata file" and upload the SP metadata file you downloaded. If you are a ListPlex cloud hosting customer, use the file downloaded from the SP Metadata URL provided by L-Soft hosting support.

Click on "Edit" in the "Attributes & Claims" box and configure Entra to use "Email address" for SAML protocol's NameID.

(If your users' email addresses in Entra don't match the email addresses used in LISTSERV, you might want to define a custom transformation rule to construct the desired email addresses.)

Configuring the LISTSERV SAML Extension

Now that you have finished the configuration in Entra (IdP), you can proceed to configure the LISTSERV (SP) part.

In Entra, take a note of the "App Federation Metadata Url" like the one shown below:

(If you are a ListPlex cloud hosting customer, provide your "App Federation Metadata Url" to L-Soft hosting support and skip the rest of this section.)

Once you have the IdP Metadata Url ready, you can continue to the next step where you will need to edit two JSON files in the SAML folder: samlsettings.json and saml.merge.json.

samlsettings.json

Open the SAML configuration file named samlsettings.json. The initial content should have "IdpProfiles" as an empty list:

{
  "WaUrl": "https://listserv.example.com/scripts/WA.EXE",
  "ServiceUrl": "https://listserv.example.com/sso",
  "IdpProfiles": [],
  "EnableSetupPage": true
}

Add your IdP information into "IdpProfiles", for example:

{
  "WaUrl": "https://listserv.example.com/scripts/WA.EXE",
  "ServiceUrl": "https://listserv.example.com/SSO",
  "IdpProfiles": [
    {
      "Name": "Entra",
      "Id": "entra",
      "MetadataUrl": "https://login.microsoftonline.com/xxxx",
      "Enabled": true
    }
  ],
  "EnableSetupPage": true
}

Name: Enter "Entra" or whatever you prefer. This name will be displayed as part of an SSO login button on the LISTSERV login page.
Id: This is a unique alphanumeric ID for internal IdP identification. You can enter "entra" or a random alphanumeric string.
MetadataUrl: Paste the "App Federation Metadata Url" that you copied from Entra here.
Enabled: Set to true to enable this IdP with LISTSERV.

Note that in order for the changes to "IdpProfiles" to take effect, you need to use saml.merge.json with your LISTSERV postmaster credentials.

saml.merge.json

This file is used for synchronization between settings in samlsettings.json and LISTSERV – for example, site variables and web templates. Such synchronization must be authorized by someone with LISTSERV postmaster access. Here is how:

1. Edit or create a file named saml.merge.json in the SAML folder, in the same location as samlsettings.json.

2. Copy the following information into the file, and use your postmaster credentials for the "Email" and "Password" fields.

{
    "Email": "postmaster@example.com",
    "Password": "password",
    "Action": "INIT"
}

Note that if you have previously done this step, you can change the value in "Action" to UPDATE to avoid initializing twice.

3. Restart the website under IIS or the SAML web application on Linux.

4. Go to the setup page again (for example, https://listserv.example.com/sso/setup) to make sure that the web application comes up without any errors. If it doesn't, check the logs at /logs/listserv-saml-yyyymmdd.log for details.

For security reasons, the saml.merge.json file will be automatically deleted after synchronization. If you would prefer to disable this auto-deletion, add this setting to samlsettings.json:

{
...
"KeepSamlMerge": true
}

Note that any changes to samlsettings.json requires a website/webapp restart to be loaded.

Testing the Single Sign-On Integration

Now, let's do a final check on the setup page to see if the profile listed matches what your IdP provides. If everything looks good, you can visit the LISTSERV login page, where a new sign-in option, in this case "Single Sign-On (Entra)", should show up below the usual email and password form. This is where users can log in to LISTSERV through Entra's SAML SSO mechanism that you have just configured.

We recommend disabling the setup page once in production by setting the EnableSetupPage property to false:

{
...
"EnableSetupPage": false
}

Enabling Single Logout (Optional)

To enable Single Logout, you need to enable the SLO from both the SP and IdP ends.

(If you are a ListPlex cloud hosting customer, ask L-Soft Hosting Support for a single logout Url and jump to Step 3 below.)

1. Enable SLO in LISTSERV SAML by adding "SLO" to the IdP profile and setting it to true in samlsettings.json:

{
  ...
  "IdpProfiles": [
    {
      "Name": "Entra",
      "Id": "entra",
      "MetadataUrl": ...,
      "SLO": true,
      "Enabled": true
    }
  ],
  ...
}

2. Restart LISTSERV SAML. You should see the following in the log file:

[XX:XX:XX INF] SLO for 'Entra' has been enabled.

3. Open the SAML app in Entra and go to "Manage > Single sign-on > SAML". Click on the "Edit" button in the "Basic SAML Configuration" box and enter the "SingleLogoutUrl". Alternatively, you can download the updated SP metadata and upload it in the Entra app.