HOWTO: Using LDAP with ProjectForum

Last modified 6/23/2006.

It is possible to use an existing external authentication mechanism such as LDAP to manage user accounts, so that passwords etc. are provided by an existing mechanism, rather than managed separately in ProjectForum.

Note: External authentication support is only available in the Enterprise version of ProjectForum (and the corresponding Campus version of CourseForum), which offer a centralized user account model. External authentication support is not available in the regularly licensed versions of the software.

At this point, external authentication support is a "hidden" feature; while it appears to work quite well in our tests, because of both limited experience with it and particularly the current complexity, we have not promoted this to a "visible" feature.

Integrating with Authentication Mechanisms

ProjectForum does not build in support directly for any particular external authentication mechanism (e.g. LDAP). Instead, it offers a generic gateway by which such a system may be integrated. This takes the form of a small web API that the external system must implement, which ProjectForum will then invoke to retrieve user information.

In practice, this usually means that a simple "conduit" must be written, usually as a web CGI, which will then talk directly to the external authentication system. This CGI conduit must also be running somewhere, typically on another web server either located on the machine running the authentication system, or one close by that has access to it.

An LDAP Example

Because ProjectForum's interface for external authentication is "neutral", most any such system can be hooked into, with a little bit of work.

Here we provide an example of a conduit written as a CGI in the Tcl scripting language. The CGI is a wrapper around the widely-available command line LDAP search program "ldapsearch". It implements the API needed by ProjectForum, and translates that into calls to ldapsearch.

You can download the short CGI file here (save it as ldap.cgi): ldap.cgi.

You will also need the CGI library support file it uses (save it as cgi.tcl): cgi.tcl.

Installing and Customizing the Conduit

Copy "ldap.cgi" and "cgi.tcl" to a directory accessible by the web server where you'd like these scripts to be run. You'll need to set things up so that the "ldap.cgi" will be executed as a CGI script by your web server. You'll also need a copy of "ldapsearch" (or a comparable command line program) on that machine.

You'll definitely need to modify the variables at the top of ldap.cgi. Use a text editor to configure them to your local LDAP setup (e.g. specifying the LDAP host, LDAP domain name, etc.) so that your LDAP server can be queried. Tweaking the parameters in the file will provide "ldapsearch" with different parameters, so it may take some experimentation to figure out exactly what the right options are.

Verify that the CGI is working correctly. You should be able to do this by loading a query like the following into your web browser:

http://127.0.0.1/ldap.cgi?op=signin&userid=johns&password=secret

This should return a response like:

status ok
username John Smith

Configuring ProjectForum

The next step is configuring ProjectForum to use your newly installed conduit for authentication.

Note: As always, try this first on a separate copy of your site, not a production version.

Make sure that ProjectForum is running, and that you've already entered the Enterprise mode license key.

Visit the following address: http://<site>:3455/admin/externauthentication.html

Enter the URL of the ldap.cgi program running on your other web server ("http://127.0.0.1/ldap.cgi" in the example above).

All user accounts should now be read from the LDAP server rather than the database stored as part of the ProjectForum site.