Caucus LDAP "How-to"

(Last revised 28 February 2003.)

Caucus 4.4 provides a completely new way of handling user login and authentication that can significantly improve your integration of Caucus with other web pages and web applications.  In particular, logins may now authenticate off of an LDAP database.  This document describes how to modify the Caucus "swebd.conf" configuration file to use LDAP.

  1. Turning on LDAP authentication in Caucus
    Edit the file SWEB/swebd.conf in the Caucus home directory.  Look for the parameter "PW_Prog".  This selects the "password program" used for Caucus user authentication.  It can have the values:

    • internal
      This means that Caucus does its own verification and modification of a "flat-file" or "passwd" style password file.  (The specific file is named in the PW_Path parameter.)

    • ldap
      This means that user authentication is done off of an LDAP database.  The database host and related values are specified in other parameters.

    • pathname
      Where pathname is the full path to an executable program that is run by Caucus when it needs to authenticate a user, or change authentication information.  This program must follow a clearly defined standard for responding to requests from Caucus.  A template program for this purpose is included with your Caucus kit, or can be downloaded from here as cpw2.c, pwactions.c, and xorstr.c.

    In order to use LDAP, just change the value of PW_Prog to be "ldap".  But you can also specify multiple values, e.g. 

       PW_PROG    ldap internal
    would mean "first check user authentication against the LDAP database; if that fails, then check authentication against the internal (passwd file) method".

  2. Specify the LDAP host
    Enter (or uncomment) an LDAP_Host parameter line, of the form: 
       LDAP_Host  ldapserver.somewhere.com  [port-number [ssl]]
    Values in square brackets are optional.  If you do not specify a port number, Caucus defaults to port 389.  If you need to use SSL, you must specify the port number (typically 636) and the literal word "ssl", separated by at least one space.

  3. Authenticate by binding
    The simplest way to use LDAP for Caucus user authentication is to attempt to bind to a particular user on the LDAP server, with that user's password.  If the bind fails, authentication fails.  If it succeeds, the user is authenticated and Caucus logs them in.

    This is accomplished with the LDAP_BindAs parameter.  The value must be the LDAP query string, with the actual userid replaced with a "%s", and the entire string followed by a space and another "%s".

    The exact format, of course, depends on the schema that you use on your LDAP server.  Here are some examples: 

       LDAP_BindAs    uid=%s,ou=people,o=myuniversity.edu %s

   LDAP_BindAs    user=%s,dc=ldapserver,dc=mycompany,dc=com %s

    In addition to the LDAP_BindAs parameter, you'll also need the following: 

       LDAP_Can_Verify  on
   LDAP_Can_Add     off
   LDAP_Can_Change  off
   LDAP_Can_Delete  off
   LDAP_Can_Reset   off

    All this means is that LDAP can be used to authenticate Caucus users, but that Caucus cannot add new users, change their passwords, delete their authentication information, or reset their passwords.  (Future versions of Caucus may support these features, although it may be that this is simply better done in the LDAP management client than in Caucus.)

  4. Authenticate by lookup
    A different, and more complicated, approach is to bind to the server, attempt a lookup on the user, and see if the encrypted passwords match.  This approach is not recommended, but it is possible.

    In this case, LDAP_BindAs should be either empty (unauthenticated aka public aka anonymous bind) or a specific dn that has access to read (presumably encrypted) passwords.  (In the latter case, the first word is the binding, and the second word is the password to bind with, if any.)

    Then specify parameter LDAP_UserDN as the dn for the specific user, replacing the actual userid value with "%".  For example: 

       LDAP_UserDN   uid=%s,ou=people,dc=myhost,dc=com

    Finally, specify parameter LDAP_pwname as the name of the user's attribute that contains the encrypted password.  This is typically called "userPassword": 

       LDAP_pwname   userPassword

    As in #3, add the LDAP_Can parameters: 

       LDAP_Can_Verify  on
   LDAP_Can_Add     off
   LDAP_Can_Change  off
   LDAP_Can_Delete  off
   LDAP_Can_Reset   off

  5. Troubleshooting
    If you run into trouble implementing either of these methods, first test your "bindas" strings with a command-line LDAP client such as ldapsearch. 

    If you still have problems, contact CaucusCare at support@caucuscare.com.  We can provide you with a test client program that reads the information in the swebd.conf file and displays diagnostic results.