Q: How can I troubleshoot problems logging in to LISTSERV with SAML?

By Jacob Haller
Senior Support Engineer, L-Soft

LISTSERV 17.5 introduced a new feature that enables single sign-on integration through the SAML protocol, facilitating a unified login experience and authentication process across multiple platforms. If you're encountering problems with this integration, this tech tip will go over a few common scenarios and give troubleshooting tips to get you up and running.

Note that this tech tip assumes that you have already read the SAML Single Sign-On Installation Manual and attempted to configure LISTSERV to use SAML for authentication according to those instructions.

Getting Started with Troubleshooting

The first place to look when troubleshooting SAML problems is the current LISTSERV log file. Under Windows, it's located in the listserv\log\ directory in files named LISTSERV-yyyymmdd.LOG, where 'yyyy' is the four-digit year, 'mm' the two-digit month and 'dd' the two-digit day of the month. Under Unix, it's usually located in the ~listserv/ directory in a file named listserv.log. Alternatively, a different location may be specified in ~listserv/go.user.

In the log file, look for entries showing X-LOGIN ... AS ... commands, for example:

9 Feb 2026 16:35:26 From [ANONYMOUS]: X-LOGIN ssouser@example.com AS chris@example.com HEXPW PW=[redacted]

Normally, when SAML logins are working, this should be followed by a line with an ***OK*** code indicating success, like this:

9 Feb 2026 16:35:26 To [ANONYMOUS]: ***OK*** A03F4F4549AD16945C chris@EXAMPLE.COM

If you get different responses, here's what they mean and what to do if you get them.

BADPW

If the SAML application wasn't able to authenticate to LISTSERV, then you might see the following:

9 Feb 2026 16:35:26 To [ANONYMOUS]: ***BADPW***

This generally means that the LISTSERV password of the service user, ssouser@example.com in the above example, doesn't match what's been set in the SAML application. To fix this, prepare a file named saml.merge.json with postmaster credentials:

{
    "Email": "pm@example.com",
    "Password": "password",
    "Action": "adduser"
}

Replace pm@example.com with an email address that is listed in the POSTMASTER site configuration setting in LISTSERV and password with the LISTSERV password of that address. Copy the file to the saml directory.

What to do next will depend on how you originally set up SAML.

If the SSO user was automatically generated by the SAML application (the most common setup), simply restart the SAML program or the application pool for the change to take effect.
In special cases (for example, if you have LISTSERV configured to use LDAP for authentication), you may have used a custom SSO user. Details about this sort of setup can be found in Section 8.4 of the SAML Single Sign-On Installation Manual. If you have this sort of setup:

1. Open samlsettings.json in the saml directory and add the updated credential to SsoUser and SsoUserAuth properties. It should look something like this:

{
  ...
  "SsoUser": "<your_sso_user_email>",
  "SsoUserAuth": "<your_sso_user_password>",
}

Note that the SsoUser address is the user described in Section 8.4 of the above-linked document and should be different from the postmaster account you used in saml.merge.json.

2. Restart the SAML program or the application pool for the change to take effect.

3. Remove SsoUser and SsoUserAuth from samlsettings.json.

PRIVUSER

This response code indicates that you are logging in using a LISTSERV postmaster account, but LOGIN_AS_POSTMASTER_ALLOWED is not set to 1 in the LISTSERV site configuration.

9 Feb 2026 16:35:26 To [ANONYMOUS]: ***PRIVUSER***

Normally, the SAML application updates this setting for you, but there are a few situations where it wouldn't.

If the PostmasterNoSSO property has been set in samlsettings.json in the saml directory.
If the LOGIN_AS_POSTMASTER_ALLOWED setting was manually changed by a LISTSERV administrator after the script ran.
If the SAML script was unable to update the setting for some reason.

As a quick fix, you can manually set LOGIN_AS_POSTMASTER_ALLOWED to 1 under "Server Administration > Site Configuration". However, we also recommend checking the SAML log file (in saml/logs/) to see if there are any errors.

ERR You are not authorized to log in as another user.

This response code indicates that the SSO service user isn't listed in the LOGIN_AS_ALLOWED_USERS setting in the LISTSERV site configuration.

9 Feb 2026 16:35:26 To [ANONYMOUS]: ***ERR*** You are not authorized to log in as another user.

Normally, the SAML application should automatically add the user to the setting when you run the merge with ADDUSER or INIT. This error suggests that either it was unable to do this for some reason, or the LOGIN_AS_ALLOWED_USERS setting was later manually changed by a LISTSERV site administrator.

You can manually add the address under "Server Administration > Site Configuration". However, as above, we also recommend checking the SAML log file for any errors.