Table of Contents Previous Next Index

Section 7 LISTSERV and LDAP

Section 7 LISTSERV and LDAP
LISTSERV can interface to LDAP servers to authenticate user logins, to insert LDAP attributes in mail-merge distributions, as well as to implement Dynamic Queries (see Section 9 Dynamic Queries for more information).
The following diagram shows the LISTSERV 15.5 LDAP architecture, in relation to other components:
Note: For clarity, Dynamic Query functions have been omitted from the diagram, but they also interface with the LDAP functionality.
The LDAP interface is at the same level as the DBMS interface – not at the level of the vendor-specific SQL drivers. Quite simply, LDAP servers do not “speak” SQL. To support LDAP, we had to teach the mail-merge and authentication modules to “speak” LDAP. This is why there is a new syntax for every LDAP-related function.
At this point, LISTSERV only queries LDAP directories. It will never try to make any changes, so it should not be given write access to the directory.
7.1 Configuring LDAP in LISTSERV
The first step in using LDAP with LISTSERV is to add one or more LDAP servers in the LISTSERV site configuration. This can be done via the LISTSERV web administration interface (the preferred method), or alternately by adding the entries manually to SITE.CFG or ‘go’.
Each LDAP server is given a nickname in the LISTSERV configuration, similarly to DBMS data sources. You can also configure one unnamed LDAP server, again like with DBMS data sources, but it is probably less confusing to assign a nickname to every LDAP server.
Three configuration variables must be defined for every LDAP server:
The hostname and optional port of the LDAP server. The exact format depends on your operating system and LDAP library; LISTSERV passes this string to the LDAP library as it is. On unix, SSL encryption is requested by prepending ‘ldaps://’ to the hostname. On Windows, the ‘ldaps://’ prefix is not available, but setting the port to 636 automatically requests SSL.
The userid and password that LISTSERV should use in order to login to the LDAP server. The exact format of the userid depends on your LDAP server. LISTSERV does not attempt to parse or reformat these variables. If the password is the empty string, most LDAP servers will perform an anonymous login. If both userid and password are the empty string, LISTSERV will attempt a default login, as defined by the LDAP library for your operating system. Under Windows, LISTSERV will be logged in with its current domain credentials (assuming it is connecting to an Active Directory server), and this usually provides sufficient access – try it before configuring a userid and password.
If the LDAP server is to be used to authenticate LISTSERV users, the following variables must also be defined:
The ‘distinguished name’ that should be the ‘base’ for searches when LISTSERV looks for a user account (see below for an explanation of the authentication process). This can be used to restrict LISTSERV access to a particular organizational unit within the enterprise. If omitted, LISTSERV tries to guess the DN that will admit any Active Directory Windows account, but this is a difficult guess to make, and of course you may not even be connecting to Active Directory.
The LDAP ’filter’ that should be used when looking up user accounts (if this filter returns at least one entry, LISTSERV allows the user to try and log in; otherwise, the login is rejected, even if the user would otherwise be able to log in to the LDAP server with the supplied credentials). Any occurrences of ‘%s’ are replaced with the user’s full e-mail address, while ‘%u’ expands to just the userid and ‘%h’ expands to the hostname. If omitted, LISTSERV uses a filter that is suitable for most Active Directory installations.
In addition, the following optional variables can be defined:
The name of the attribute that ordinarily specifies a user’s e-mail address in this directory. This is used as a default value in searches and can be overridden. If omitted, it defaults to ‘mail’ (suitable for Active Directory).
The name of the attribute that ordinarily contains the user’s full name. Defaults to ‘name’.
7.2 Using LDAP for Mail-Merge
Because of its complex, machine-friendly syntax, LDAP is primarily suited for scripting. While it is relatively easy for a programmer to write a script that sends a weekly notice to every member of a particular department, it is not realistic to expect ordinary list owners or end-users to understand the intricacies of LDAP and devise working search filters. For instance, to select all users in an Exchange database, one would have to use the following filter:
L-Soft expects that LDAP-based distributions will be created by customer-developed scripts – either intranet web scripts or traditional ‘cron’ jobs or scheduled tasks. At this point, there are no plans to provide a web interface page into which raw LDAP search filters could be entered.
To create an LDAP-based distribution, a script uses the DISTRIBUTE command and specifies an LDAP keyword as follows:
DISTRIBUTE … LDAP=YES(SERVER=nickname,E-MAIL=attribute,PARTS=attribute)
The syntax of this keyword is essentially the same as for SQL-based distributions (“DBMS=”):
Identifies the LDAP server to be queried. If omitted, the default (unnamed) LDAP server is used.
Identifies the name of the directory attribute containing the recipient’s e-mail address. If omitted, the value of LDAP_DEFAULT_EMAIL_nickname is used.
The name of an optional directory attribute containing a list of message parts that the recipient subscribes to. Although this mail-merge feature is unlikely to be used with LDAP, it is available if desired.
Similarly to SQL-based distributions, the ‘TO’ DD contains a list of LDAP search statements, rather than a list of actual recipients. Each line in the ‘TO’ DD can be one of the following statements:
The ‘distinguished name’ of the ‘base’ of the LDAP search. Mandatory.
The LDAP search filter for the search. Mandatory.
A list of directory attributes of interest (used in the mail-merge). If omitted, all directory attributes are made available. Attribute names are not case-sensitive. The main purpose of this statement is to improve search performance if there are many irrelevant attributes in the directory.
Note: The E-MAIL and (if enabled) PARTS attributes must be specified or the distribution will fail.
Optionally changes the scope of the search from the default (SUBTREE).
Starts the search. This command allows multiple LDAP searches to be performed in the same distribution. If there is only one search, this command is optional – LISTSERV automatically starts the search when it reaches the end of the ‘TO’ DD.
For instance, this search will select all Windows users in the EXAMPLE.COM domain with a valid e-mail address:
FILTER (&(objectcategory=person)(objectclass=user))
ATTRS Name Mail Phone
7.3 Using LDAP for Authentication
LISTSERV can be configured to use one or several LDAP servers for authentication (user login). You can choose to allow users without an LDAP account to log in with an internal LISTSERV password, or to restrict access to users with an LDAP account.
LDAP authentication is enabled by defining the following configuration variables:
LDAP_PW_SERVERS=nickname1 [nickname2 […]]
The list of LDAP servers to be queried (in the specified order) for user accounts. Be sure to enter server nicknames, not hostnames.
LDAP_PW_ONLY=0 or 1 (default: 0)
If set to 1, only users with an LDAP account are allowed to log in to LISTSERV; other users will only be able to access LISTSERV anonymously.
Warning: Make sure to test your LDAP settings before enabling this option, or you will not be able to undo it from the web interface! Enabling this option on a server that previously had external users is likely to result in significant confusion for the external users, whose passwords will no longer work.
LDAP_PW_REQUIRE_SSL=0 or 1 (default: 1)
Whether or not LISTSERV should accept LDAP passwords transmitted to the web interface in plain text. By default, LISTSERV will only attempt to verify passwords transmitted over SSL.
Note: This option does not control LISTSERV’s own use of SSL when communicating with the LDAP server. See the LDAP_SERVER_nickname variable.
SIGNUP_REQUIRE_SSL=0 or 1 (default: 0)
Similar to the above, but affects all LISTSERV passwords, whether LDAP or internal. Can be used without enabling LDAP authentication.
7.3.1 The LDAP Authentication Process
When LDAP is enabled, LISTSERV goes through the following steps to log in a user:
The servers listed in LDAP_PW_SERVERS are examined in turn, in the order in which they were listed. For each server, LISTSERV executes the search configured with the LDAP_PW_BASE_nickname and LDAP_PW_FILTER_nickname variables. LISTSERV stops at the first successful search, or when there are no more LDAP servers to query.
Switches to internal (non-LDAP) login if LDAP_PW_ONLY=0. The login will be validated against the user’s internal LISTSERV password, if any, or the user will be prompted to create a LISTSERV password.
Rejects the login if LDAP_PW_REQUIRE_SSL=1 and the login request did not come over an SSL session. In this case, LISTSERV does not even try to verify the password.
7.3.2 A Note on the “Require SSL” Option
The purpose of the “require SSL” option is to prevent ordinary, non-malicious users from jeopardizing their login credentials for their personal convenience, for instance by typing clear-text passwords in e-mail requests because it is faster than waiting for a confirmation ‘cookie’ at the particular Internet café where they are reading their mail. The “require SSL” option effectively disables these login attempts and forces users to log in using the web interface and SSL.
As LISTSERV does not directly process SSL sessions, it has no first-hand knowledge as to whether SSL was used to encrypt the login session or not. It is the web server that handles the SSL session with the user’s browser, notifies the LISTSERV web interface that SSL was used, and the web interface script in turn notifies LISTSERV that the password was not sent in clear text. LISTSERV has no way to verify this representation or guarantee that SSL was in fact used to transmit the password. This being said, there is no advantage for a malicious user in logging in to LISTSERV with his own credentials over an unencrypted connection. The malicious user’s interest is for other, non-malicious users to expose their passwords by sending them in clear text, so that the malicious user may gather them.
7.3.3 Using the Optional LDAP_BW_Bind Configuration Variable
The optional LDAP_PW_BIND site configuration variable is now available in all LISTSERV 16.0 builds. This variable contains the string to format and use when logging on a user. The default is "%n", which works "out of the box" with Active Directory and, in most cases, with OpenLDAP. For other LDAP implementations, or if a different bind string is required for your local installation, it can be defined in this setting and may use the %u/%h/%s escapes.
Examples (for use with the "default" LDAP server):
unix: LDAP_PW_BIND="%n"
Additionally, this variable, like most of the other LDAP-related variables, can also take an optional server-name attribute, e.g.,
The above example assumes that LDAP_SERVER is set to include MYSERVER.
Important: The default value for LDAP_PW_BIND is now "%n".
7.4 Using LDAP Over SSL for the Solaris Operating System
Setting up LISTSERV to authenticate via LDAP with SSL can be challenging. There are several scenarios that are dependent primarily on the version of Solaris you are running.
There are two LISTSERV kits involved:
7.4.1 SCENARIO 1: Using the Solaris 8 LISTSERV Kit on any Version of Solaris
This kit uses a statically linked copy of OpenLDAP. None of the Solaris instructions apply because Sun’s LDAP is not used at all. STOP HERE and use the Instructions for OpenLDAP instead.
7.4.2 SCENARIO 2: Solaris 8 with the Solaris 10 LISTSERV kit
This scenario assumes and REQUIRES that you are running Solaris 8 with Sun's LDAP library.
If you are running OpenLDAP on Solaris 8, you MUST use the Solaris 8 kit, and the Instructions for OpenLDAP.
In this scenario, you must first take the following steps:
Confirm that you have the ‘certutil’ utility on your system AND that it operates in the old cert7.db format. This utility does not come pre-installed and is unlikely to be in root’s default path. This would be something you or a colleague installed manually at some point, presumably in /usr/local/bin, but it could be elsewhere.
If you do not have or cannot find certutil, download the “Directory Server Resource Kit 5.2.1” from Sun and install it. This contains a suitable certutil utility.
At this point, you may continue with the Generic Solaris Instructions found below.
7.4.3 SCENARIO 3: Solaris 9 with the Solaris 10 LISTSERV kit
This scenario will generally be unworkable because of certificate incompatibilities introduced by Sun in Solaris 9. Although Sun's LDAP for Solaris 9 requires certificates to be formatted in the older cert7.db format, the certutil utility that ships with Solaris 9 creates cert8.db format files.
Important: We strongly recommend that Solaris 9 users wishing to use LDAP with LISTSERV contact Sun directly for support on this issue. L-Soft is unable to provide support for this issue as it is a problem that only Sun can resolve.
If you have a Solaris 8 system available, you can use it to follow the Generic Solaris Instructions, below, and then FTP the resulting certificate files to your Solaris 9 system.
If you do not have a Solaris 8 system available, you could download and install the "Directory Server Resource Kit 5.2.1" from Sun, and install it in a temporary directory.
Important: If you install the Directory Server Resource Kit 5.2.1 under Solaris 9, then you must NOT overwrite anything that came with your Solaris 9 system.
Alternately, and perhaps preferably, Sun may have a conversion program or another way to help you with this incompatibility issue. Please contact Sun directly for more information.
7.4.4 SCENARIO 4: Solaris 10 with the Solaris 10 LISTERV kit
Solaris 10 does understand the cert8.db files created by its version of certutil. You will find certutil pre-installed in /usr/sfw/bin, so just follow the Generic Solaris Instructions. Note that /usr/sfw/bin is not in root’s path.
7.4.5 Generic Solaris Instructions
# ls /var/ldap/*.db
STOP NOW AND GO TO STEP 2 if there are already files in there.
# <path-to-certutil>/certutil –N –d /var/ldap
# ls /var/ldap/*.db
# chmod 644 /var/ldap/*.db
Do not provide a password. Just type RETURN twice. Verify that you created the right ‘flavor’ of database: cert7 for Solaris 8 and 9, cert8 for Solaris 10. Otherwise you need to start again with the right certutil.
Obtain the public SSL certificate for the LDAP server you want to connect to. This example assumes you used the standard PEM exchange format (base64-encoded ASCII), there are other formats that may require additional or different switches. We will assume that you have saved the certificate in a file called cert.txt.
# <path-to-certutil>/certutil –A –n "nickname" –d /var/ldap –a –t CT –i cert.txt
The nickname is just a dummy name for your convenience in remembering what this certificate is for.
That’s it! You are now set up for LDAP over SSL to that particular server. Remember to specify port 636 in LISTSERV’s configuration, for instance:
7.4.6 Instructions for OpenLDAP
This section contains the OpenLDAP instructions, which are the same regardless of the brand of unix you are running.
Obtain the public SSL certificate for the LDAP server you want to connect to, in PEM format (ASCII). If you receive the file in a different format, it is probably easier to ask the LDAP server administrator for a PEM file in ASCII than to try and convert it yourself. If you must convert the file, there are too many possible scenarios to cover here, but check the man pages for the openssl command.
Save this file in the home directory of the ‘listserv’ user as ‘SSL.pem’. If working as root, make sure the ‘listserv’ user has at least read access.
$ cat > ~listserv/.ldaprc
TLS_CACERT /home/listserv/SSL.pem
Substitute the path to the home directory for the ‘listserv’ user. You may or may not be able to use ‘~listserv’, but an explicit path will always work. As before, if working as root, make sure the ‘listserv’ user has at least read access.
That’s it! Remember to specify ldaps access, for instance:
7.5 Dynamic Queries
Although Dynamic Queries are primarily based on the LDAP interface, they are described in Section 9 Dynamic Queries,since they support both LDAP and DBMS data stores.
7.6 Known issues and restrictions
The following known issues and restrictions exist:
OpenLDAP library required to re-link on unix. Customers wishing to re-link ‘lsv’ on unix will have to install the OPENLDAP library (except on Tru64 and HP-UX), even if they do not want to use LDAP.
Static library support not tested on all unix brands. Our goal is for unix builds with LDAP functionality to work on target systems that do not have the dynamic LDAP library, but we have not tested this on every system.

L-Soft international, Inc.