The new Caucus 4.4 login method

(Last revised 13 November 2002.)

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.  This document takes you on a step-by-step tour of how this login method works, and how to use it in doing such integration.

  1. How does it work?
    Caucus login is now done through a static HTML page.  Basically, it contains a form, with a field for userid, a field for password, and a "submit" button.  When the form is submitted, it passes the userid and password on to a Caucus "CML" page called login.cml, that is interpreted by a Caucus "swebs" process (see the architecture description for details). 

    The login.cml page checks to see that the userid and password are correct, and then generates a pair of what are called "session cookies", small chunks of data that reside in the browser.  From there on, each Caucus CML page tests the values in those cookies to determine if the user logged in properly. 

    (Note that session cookies are not like the sometimes-frowned-on disk cookies -- they automatically evaporate when the browser exits, and never land on the user's hard disk.  Most generation-5 browsers allow the user to enable or disable session cookies and disk cookies separately.)

    When the user logs out of Caucus (presses the Quit button), those cookies are wiped clean.  If the same user wants to go back into Caucus, they must login all over again.  If the user doesn't press Quit, but "times out" (is idle for longer than a configurable period, typically 60 minutes), the cookie automatically becomes invalid, and the user will be forced to login again. 

    (This greatly reduces the risk of a public PC being left "logged in to Caucus" by a careless user.)

    One of the advantages of this method is that you can open two (or more) windows, and simultaneously login as different users.  Each user is completely separate, as if you were logging in from completely different PCs.

    The default Caucus login page is automatically created in the Caucus public_html directory, and it is called "caucus.html".  Caucus 4.4 also creates another page called "caucusswl.html", which allows login via the "old style" 4.3 web-server-based authentication.

  2. Making your own HTML login page
    The default caucus.html file has a lot of formatting, embedded Javascript, and other "stuff" in it.  If you want to build your own, or integrate the required elements into an existing HTML page, you may find it easier to work with one of the "stripped-down" files below.  (Just click on one and then tell your browser to "view source".)

    But whatever you do, don't change the caucus.html file -- see section 3 below.  Make up a new file of your own.  (Or else make sure that you really understand the inner workings of the form_add_querystring function!)

    1. c44login_med.html
      This file has 5 elements: userid field, password field, submit button, link to reset password, link to self-register a new user.  In addition, this file

      • Automatically puts the cursor in the userid field (see body onLoad condition).
      • Verifies that the user's browser accepts session cookies (see cookies_allowed function).  If not, it offers a link to the "old style" Caucus login page.
      • Defines the order in which the <tab> key hops from field to field (see tabindex option).
      • Automatically submits the form if the user types a password and then presses the Enter key (see checkEnter function).

    2. c44login_low.html
      This file is the absolute "bare-bones" version.  It has a userid field, a password field, and a submit button.  No password resetting, no user registration, no Javascript.

    The proper approach for your own site probably lies somewhere in between these two files.  We recommend that you study them, and decide which features you'll want to keep.  If you have questions, please join our "Technical Support" conference at caucuscare.com.

    Submit button:  You can use any kind or name of submit button, including "image" buttons.  Caucus cares only about the names of the userid and password fields.

    Interface note:  If you have worked with multiple Caucus interfaces, you'll see that the sample files above all enter the default "CC44" interface.  You can change this in your own HTML pages by simply changing "CC44" in those files to the appropriate interface name.  Make sure to use the exact capitalization that you used in defining your own interface(s).

  3. http://yourhost.com/caucus URLs
    Certain features in the default caucus.html are required if you are using the so-called "special Caucus URLs", such as http://yourhost.com/caucus.  Those URLs specifically use the caucus.html file, so it is best not to change that file, but make your own files (as in section 2 above).

    In particular, the Javascript function "form_add_querystring" picks up any special information in the URL (such as a conference name or an "@XYZ" interface designation) and makes sure it gets passed along to the login.cml page.  That ensures that "special" URLs like:

      http://yourhost.com/caucus/@XYZ/welcome

    get parsed correctly, and take the user into conference "welcome" using interface "XYZ".

  4. Integrating with other web applications
    The so-called "Holy Grail" of web services and web applications is single signon -- where a user logs in once, and is transparently and automatically logged in to any or all of the applications, as needed.

    Caucus 4.4 makes this a lot easier, but it can still be tricky to implement, depending on the other application(s).  There are two issues, each of which have several possible solutions.  For purposes of discussion, let's assume there are two applications we'd like to integrate: Caucus and (the mythical) CoolApp.

    1. Authentication source.  The issue is to make sure that Caucus and CoolApp are authenticating the user (checking userid and password) against the same source of userid and password information.  Here are several possible ways to make this happen, in more or less increasing order of difficulty:

      1. If CoolApp can authenticate from an LDAP server, the issue is solved.  Caucus can be set to authenticate against any LDAP server; see the comments in the authentication section of the Caucus swebd.conf configuration file. 

      2. If Caucus and CoolApp can run on the same server, then they both might be able to use the same web server authentication method -- really the web server is authenticating the user, and Caucus and CoolApp just piggy-back off of that.

      3. Caucus also has the ability to do its authentication via any arbitrary program.  CaucusCare provides a template program that must be called a certain way, but otherwise can do whatever it needs to, to get at the CoolApp authentication source. See cpw2.c, pwactions.c, and xorstr.c for details.

      4. The last-ditch option is to force Caucus to always use the same ids and passwords that CoolApp uses (or vice versa).  In this scenario, one application must be treated as the "master" application, in which all users are registered, and from where they start.  Once inside, then the user must be able to click on a link that takes them to the "slave" application.

        This requires that the master must be able to automatically (without additional user interaction) register users in the slave application, and change passwords in the slave when they are changed in the master.

        Caucus has the capability to run as either master or slave, although the full details are beyond the scope of this document.  See the "intg" files created by your Caucus installation for templates.

    2. Supplying userids and passwords.  In most cases, we still need to get the userid and password into Caucus and CoolApp.  There are three ways of going about this:

      1. Caucus as master.  In this approach, the user first logs into Caucus.  Then a page in Caucus has a link that opens up a window running CoolApp.  Caucus has a "CML function" that remembers the userid and password typed by the user, and can build that into a link that launches (and transparently logs into) CoolApp.

        Caucus 4.4 includes a working example of this, that integrates with GroupMind Express.  You can use this example as a template; see the CML/CC44/main/login_gme.cml file in your Caucus site.

        This requires, however, that CoolApp have a way to login "behind the scenes", so to speak, without actual user interaction.  This is actually quite common, and usually involves filling in a form that automatically submits itself, perhaps via the body tag onLoad condition.

      2. Caucus as slave.  Here the user first logs into CoolApp.  We assume that CoolApp has a way to remember the userid and password, and can be customized sufficiently to build a link into Caucus.

        Given a userid X and password Y, you can build a link that logs into Caucus as: 

        http://yourhost.com/reg/swebsock/0/0/CC44/main/login.cml?userid=X&password=Y

        Or you can build a <form> page that submits itself to the same URL (without the query string) and has fields named "userid" and "password", filled in with X and Y.  This is somewhat more complicated, but also more secure (in that the userid and password do not appear in a browser address bar or history list, and can also be encoded with https).

      3. Central Login Page.  A way to avoid the master/slave customizations is to start with a central login page that uses some javascript to remember the userid and password.  The central login page can then launch Caucus and CoolApp whenever needed, without requiring any further user interaction.  This is possibly the easiest solution, although it may require at least three windows (one for the central login, one for Caucus, and one for CoolApp) be present simultaneously.

      4. Cookie verification.  A completely different approach is to abandon passwords altogether, and depend on a specially formatted session cookie to verify that the user has been logged in.  In this approach, either CoolApp or a central login page acts as a master, and the Caucus login.cml page is modified to sense the existence of a specially formatted cookie, and act as if the user has logged in. 

        In order to make this method secure, Caucus probably needs to run a small custom program that performs some kind of verification operation on the cookie -- otherwise it is too easy for a good web page designer to deduce the format of the required cookie, and spoof it.  Please contact us if you are interested in pursuing such an approach.