Caucus How-To: Authentication Schemes

I. Introduction

Note:  this document refers to the web-server based authentication method used in Caucus 4.3 and earlier, and thus is primarily of historical interest.

Caucus 4.4 and up offers an alternate authentication method that has many advantages over the old method.  See the Caucus 4.4 login method description instead for details.

Caucus requires that some sort of user authentication scheme be used to uniquely identify each user.  As installed "out of the box", Caucus uses the standard web "access authorization" mechanism that grew out of the early web servers, such as the NCSA server. 

Caucus is not specifically tied to that authentication mechanism, however; a wide variety of other methods of authentication can be used with Caucus.  This page describes the fundamentals of how authentication works with Caucus, and how to integrate other methods.

 

II. More About Standard Access Authorization

In the standard web "access authorization" scheme, the web server is configured (by your local webmaster) so that a particular directory is "protected" by a list of userids and passwords. 

In Caucus' case, the web server is told that the "SWEB" directory is protected -- and the "/sweb" part of the Caucus URLs is mapped onto that directory.  Here's what happens when you start using Caucus.

1. You point your browser (or follow a link) to a URL that contains "/sweb".  (E.g. http://yourhost.com/sweb/swebsock/0/0/CS41/center.cml?0+0+x+x+x+x+x+x)

2. The web server knows that everything under "/sweb" is in the Caucus "domain", and is protected.  It tells your browser that it needs an authorized id and password to get that page.

3. Your browser pops up a dialog box, prompting you for your id and password.  The browser passes that information back to the web server.

4. The server checks this information against a file that contains a list of valid ids and passwords.  In the default case, this file is called caucus_passwd and lives in the top level of the Caucus home directory.  The file contains ordinary ("plain") text, one id & password per line.  Each line contains the id, followed by a colon, followed by an encrypted form of the password, one id/password per line.  This is the standard "NCSA flat-file" format.

   Side note:

   The mechanism by which a directory is protected by a particular userid & password file varies from server to server.  In the case of the popular Apache server, a directory is protected if it contains a file called .htaccess.  That file in turn tells Apache how the directory is protected, and points in turn to the caucus_passwd file.  For example, in a typical Caucus installation with an Apache server, the .htaccess file looks like:

      AuthUserFile   /home/caucus/caucus_passwd
      AuthGroupFile  /dev/null
      AuthName       Caucus
      AuthType       Basic
      
      <Limit GET>
         require valid-user
      </Limit>
      
      <Limit POST>
         require valid-user
      </Limit>
   

5. If your id or password are incorrect, the web server sends a rejection back to your browser, which complains to you.

6. If your id and password are correct, the web server runs the CGI program "swebsock" (see the URL in II.1, above), which communicates with the Caucus process that actually generates the HTML page.  Swebsock passes the HTML back through the web server to your browser.  (The details of this communication are described in the Caucus Architecture description.)

   The userid that you entered gets passed to the swebsock program as the value of the environment variable REMOTE_USER (or in some web servers, as the variable AUTH_USER).  This is an important note -- prior to this point, all of the negotiation about userid and password is done between the browser and the web server.  Any authentication scheme that supplies a userid to swebsock via REMOTE_USER will work with Caucus.

7. Once your browser has gotten your userid and password, it caches them, and supplies them to the web server, which in turn supplies the userid to swebsock, and so on.  This happens on every Caucus page transaction -- you're only aware of it the very first time, when the userid & password dialog box appears.

 

III. Other Forms of Authentication

As you can see from II.6 above, any form of userid-based authentication can be used with Caucus, so long as it passes the userid on via the REMOTE_USER environment variable.

Many web servers provide a variety of means of controlling userid authentication.  Most of them automatically set REMOTE_USER properly, regardless of the means of authentication selected by the webmaster.  These include:

1. NCSA flat files (as in section II)

2. DBM files (a faster, random-access binary file that stores the same information as the NCSA file)

3. LDAP (where the userid and password information is stored on an LDAP server, probably on a different machine)

4. Local host system userids.  (This is the normal scheme for Microsoft's IIS, which to the best of our knowledge does not support NCSA-style flat-files.)

You can also write your own authentication method, so long as it arranges to provide the proper value of REMOTE_USER.  If it is simply not possible to provide REMOTE_USER, please contact us at support@caucus.com.  In some cases we may be able to help you adapt the swebsock program to your authentication needs.

 

IV. Caucus' Interface to the Userid List -- Basics

Caucus includes a web-based administration tool to manage Caucus conferences, users, and general operation.  This includes the capability to manage userids and passwords.  This is an extremely useful capability -- but it comes at a price.  In order for this feature to work, Caucus must be able to modify the source of the authentication information.

In the default, NCSA-style flat-file case, this is easy.  Caucus knows how to read and write directly to the flat-file, and the following parameters in the SWEB/swebd.conf configuration file control how it does this.

PW_Prog        internal

This tells Caucus to read and write to the flat-file, directly, using its internal methods.

PW_Path        /home/caucus/caucus_passwd

Defines the location of the flat-file.

PW_Can_Add     on

Caucus is allowed to add new userids.

PW_Can_Change  on

Caucus can change passwords of existing users.

PW_Can_Delete  on

Caucus can delete userids.

PW_Can_Verify  on

Caucus can verify the correctness of a userid / password pair.

PW_Lock        on

Tells Caucus to lock the flat-file before making changes.  (Required if any of Can_Add, Can_Change, or Can_Delete are ON; otherwise it can be OFF.)

You can use these parameters to easily disable certain capabilities.  For example, suppose your web server uses flat-files, but you want to maintain the list of userids and passwords exclusively from some other utility. 

In that case you could turn Can_Add, Can_Change, Can_Delete, and PW_Lock OFF, and set the value of PW_Path to point to the proper flat-file.  Caucus can still use the file to verify users (for example, if you've turned on password confirmation from the Manager "Edit Switches" link), but it won't try to add userids, change passwords, or delete userids.  (In fact it won't even display those options.)

 

V. Caucus' Interface to the Userid List -- Advanced

Remember that you don't need any of the userid management features in order to actually use Caucus.  If you wish, you can use any authentication scheme supported by your web server (as described in section III).  Simply turn off all of the "Can" parameters in section IV.

On the other hand, if you want to use the Caucus userid management features with some other authentication scheme, it is still quite possible.  Caucus has a pre-defined interface that can talk to an external program, which in turn can read or modify the source of the userid and password information.

The "external program" must follow a carefully defined procedure to talk to Caucus.  Rather than define a specification for this procedure, we have supplied the source code for a working 'C' program, called CPW2 (Caucus PassWord program, release 2).  This program implements all of the userid and password transactions for the standard NCSA flat-file.

The source for this program consists of 4 modules:

• cpw2.c -- Main program.  Handles communication to and from Caucus.  You should be able to use this w/o modification in any application that you write.

• pwactions.c -- Function that actually performs the add, delete, modify, or verify operations.  You would rewrite this entirely for your application.

• getent.c -- Function that reads entries from an NCSA flat-file.  Probably irrelevant to any other authentication method.

• xorstr.c -- Function to compute simple exclusive-ORs.  Used to perform very simple encoding on userid & password requests from Caucus.

  You can download an archive of all 4 files as cpw2.tar.gz or as cpw2.zip.

  Once you have written an application (e.g., rewritten cpw2) to modify the authentication information, you must change the SWEB/swebd.conf configuration file to tell Caucus to use your new program.

  PW_Prog        /home/caucus/your_new_program

  Set this to the full pathname of your new cpw2-based program.

  PW_Path        /home/caucus/your_passwd_file

  Set this to the full pathname of the file your authentication method uses.  This may be irrelevant, depending on what your method is; but put something in here anyway, even if it is "xyz".

  PW_Can_Add     on
  PW_Can_Change  on
  PW_Can_Delete  on
  PW_Can_Verify  on

  Set these according to which functions your program can handle.

  PW_Lock        on

  Set this ON or OFF if your program actually makes use of the is_lock parameter passed to pw_actions().