Resources > Configuring Single Sign-On via Okta in LISTSERV

LISTSERV Tech Tip

Q: How can I configure single sign-on via Okta 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 use Okta Developer Edition as an example to illustrate the procedure of adding Okta to the LISTSERV web interface as a SAML single sign-on provider.

What is Okta? Okta is a leading identity and access management service that provides secure single sign-on, multi-factor authentication and lifecycle management for organizations. It helps streamline user authentication and enhance security. For more detailed information, you can refer to Okta's official documentation on building a Single Sign-On (SSO) integration.

Prerequisites

LISTSERV 17.5
Okta
The LISTSERV SAML Application

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
}

(On Linux, "WaUrl" usually ends with "cgi-bin/wa")

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 Okta and integrate it with the LISTSERV SAML extension.

Creating a SAML 2.0 App Integration in Okta

After logging in to your Okta admin portal, navigate to "Applications" > "Applications", where you can find all existing app integrations. Click on "Create App Integration", select "SAML 2.0", and proceed to the next step.

Give a name to the app integration (for example, "LISTSERV SAML") and, optionally, upload an icon to identify it.

Click on the "Next" button to proceed to the "Configure SAML" screen. Use the information on the setup page to fill out this form. The nomenclature for the URL is slightly different. Here is some guidance:

Single Sign-On URL: This is also referred to as the SAML Assertion Consumer Service (ACS) URL. Copy the value of "SSO/ACS Url" from your setup page and paste it here.
Audience URI (SP Entity ID): Copy the "EntityID/Metadata Url" from your setup page and paste it here.
Default RelayState: This field should be left blank.
Name ID Format: Select "EmailAddress".
Application Username: Select "Email".

Proceed to create the app integration, after which you should be able to see it under "Applications" > "Applications".

Click on the newly created app and navigate to "Sign On". Copy or take a note of the "Metadata URL" field.

Configuring the LISTSERV SAML Extension

Now that you have enough information from Okta, you can continue to configure the LISTSERV SAML extension. This is a two-step process and involves two JSON files: 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": "Okta",
      "Id": "okta",
      "MetadataUrl": "https://dev-xxx.okta.com/app/xxxx/sso/saml/metadata",
      "Enabled": true
    }
  ],
  "EnableSetupPage": true
}

Name: Enter "Okta" 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 "okta" or a random alphanumeric string.
MetadataUrl: Paste the "Metadata URL" value that you copied from Okta 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 (OKTA)", should show up below the usual email and password form. This is where users can log in to LISTSERV through Okta'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.

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

{
  ...
  "IdpProfiles": [
    {
      "Name": "Okta",
      "Id": "okta",
      "MetadataUrl": ...,
      "SLO": true,
      "Enabled": true
    }
  ],
  ...
}

2. Go to the SAML Settings page in Okta and click on "Show Advanced Settings":

1. Check the "Allow application to initiate Single Logout" checkbox.

2. Enter the value of SingleLogoutUrl under the IdP profile from the setup page in the Single Logout URL field.

3. Enter the LISTSERV SAML metadata URL in the SP Issuer field.

4. (Optional): If you wish to provide a signature certificate, you can visit the LISTSERV SAML metadata URL, copy the value from the "KeyDescriptor" > "KeyInfo" > "X509Data" > "X509Certificate" element into a text file and upload it to the Signature Certificate in Okta.

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

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