Caucus How-To: Authentication Integration Last revised: 13 November 2002

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, especially regarding integration with other web applications.  See the Caucus 4.4 login method description instead for details.

As described in How does Caucus user authentication work?, Caucus depends on the web server to actually authenticate the user -- although Caucus can, in most cases, manipulate the user file or user database that keeps track of the userids and passwords. 

II. Other Software

There is an increasing desire to "integrate" different web-based tools, such as Caucus, with each other.  With respect to authentication, this usually means that, when the tools have been "integrated", the user's expectation is that they'll only have to login once, and will be automatically recognized by both applications.

Making this happen can be either a very satisfying or very frustrating experience, depending on how each tool views user authentication.  If you have a choice of tools, it would be wise to examine how each handles authentication before making your final choice.

There are three dimensions to consider when integrating Caucus and any other tool (or any two tools):

1. Master/slave vs. peer-to-peer.
   Will one application clearly be the "master", in the sense that the users will enter via this application, and see the other application as apparently "just another feature" of the first?  Or will both applications appear as "peers", i.e. users may enter either application and somehow see or use the other from "inside"?

   The first case is often the easiest, since if the user needs to change their authentication (or potentially other personal info, such as e-mail, address, etc.), they're probably going to do it just in the one app.  The second app may even have those capabilities turned off in some manner.

   In the peer-to-peer case, you may find there's a need for both applications to inform the other of changes in authentication or personal information -- which can be a headache depending on how each handles the data.

2. Webserver authentication vs. "inside the tool" authentication.
   Where does authentication occur for each tool?  If both tools use the webserver, then shared authentication can be very simple.  If both do their own authentication, then both may have to have (added) tools to exchange information with each other.  If one uses the webserver, and the other does its own, then data exchange may have to happen with the webserver (or wherever the webserver gets its information from).

3. Same server vs. different servers.
   If both applications are using the web server to perform authentication, they had better both be running (physically located) on the same server!  Otherwise shared authentication may be impossible.

   Tools that used totally web-based "inside the tool" authentication may not care where they are, since they'll probably be exchanging information over the web in either case.  Make sure to consider how information will be exchanged, and see if the same/different server choice will impact the method of exchange.

III. Integrating with Caucus

Integrating another tool's authentication with Caucus' will typically fit into one of the situations described below:

1. Both tools use the webserver, and both read/write to the webserver's data source (such as a flat 'passwd' file) as needed.
   This is the easiest case (as long as both apps run on the same server!).  All that is needed is to make sure that both tools are considered to be in the same "authentication realm".  For Apache, this can be as simple as putting both tools under a common directory, and password protecting that directory.  For iPlanet, you choose a realm when declaring a directory or CGI application password protected -- use the same realm for both Caucus and the other app.

2. Both tools use the webserver, but the authentication data is stored in an unusual place.
   For example, Apache can be modified to do authentication against a variety of original sources -- such as LDAP or an SQL database.  This means that either Caucus or the other app or both may need to be able to read/write to that original source.  The document How does Caucus user authentication work? describes the template cpw2.c program, which can be modified to work with any original data source.

3. Caucus is the "master", and the other tool does its own authentication.
   Caucus can pass authentication information in the URL to the other app.  (This can be tricky, because Caucus may not have the user's password -- typically only an encrypted form of the password is readable.)

   Caucus version 4.35 and above has a set of "stub" CML files that can be used to pass changes in authentication and personal information, made by users or managers inside Caucus, to an outside app.  These stubs are:

   intg_create.i	Create a new user
   intg_change.i	Change an existing user
   intg_encpass.i	Get encrypted password for a user

   These files are automatically included ("called") by the CML files that perform the appropriate create or change events inside Caucus.  To use them, you must "set integration 1" in the Local/switch.i file in the appropriate CML interface directory.

   These files in turn run the corresponding shell scripts intg_create and intg_change, which are provided as template files with Caucus.  (Also included is the script intg_urlencode, which is a service utility for URL-encoding any authentication or personal information that needs to be sent over the web.)  The idea is that these files could then send user creations or changes to the other app via the web; obviously the details of precisely how that happens will vavary from app to ap  (One very useful open-source tool that may help is Curl, a command-line based web form "poster", which can be downloaded from curl.haxx.se.)

4. Caucus is the "slave" or a peer, and the other tool does its own authentication.
   This is a very difficult situation.  Even if the other app can pass authentication info to the webserver, it's still nearly impossible to avoid the browser userid/password dialog box pop-up when entering Caucus.