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:

    • LDAP_SERVER_nickname=hostname[:port]

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.

    • LDAP_UID_nickname=userid
    • LDAP_AUTH_nickname=password

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:

    • LDAP_PW_BASE_nickname=DN

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.

    • LDAP_PW_FILTER_nickname=filter

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:

    • LDAP_DEFAULT_EMAIL_nickname=attribute

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

    • LDAP_DEFAULT_NAME_nickname=attribute

The name of the attribute that ordinarily contains the user’s full name. Defaults to ‘name’.