CML Reference Guide

Chapter 4.24:  Authentication and Authorisation

 [TOP] [UP] [PREV] [NEXT]

Caucus 4.4 and 4.6 expanded the possibilies for how to do user authentication and authorisation.  "Authentication" is the way that the user provides his or her identity (userid and password) to the Caucus software.  "Authorisation" is the way that Caucus verifies the user is really who they say they are (validate userid and password against a known source of information).

There are basically three methods for handling authentication:

  1. Web-server basic authentication.  This is the original Caucus method, in which authentication is done entirely by the web server.

    The Caucus pages are run from a "protected" directory, which means that the web server insists that a user be authorised before they can see those pages.  The server sends an authentication request to the browser, which pops up a (built-in) userid and password dialog box.  The userid and password are sent back to the server via environment variables, and the server then compares them to its authorisation source (typically a 'passwd' file).

    If the user is authorised, then the server displays the pages.  The browser caches the userid and password, and sends them along with every request for a page in the protected directory.

  2. Cookie-based Caucus authentication.  This is new in Caucus 4.4.

    In this method, the user arrives at a Caucus 'login' page, which prompts for userid and password.  Caucus checks the values against its authorisation source, currently via the function $pw_verify(), and if they pass, it sends a cookie to the browser that identifies the user as authorised for the duration of this Caucus session.

    All subsequent requests for Caucus pages send the cookie to the server, which ensures that the userid is constant throughout the session. 

    Note that Caucus cookies are kept (only) in the browser's memory, they are not written to the user's hard drive.  (For more information about cookies, see wp.netscape.com/newsref/std/cookie_spec.html.)

  3. External cookie-based authentication.  This is new in Caucus 4.6.

    In this method, it is assumed that some other application has already gone through the authentication and authorisation process.  But that other application needs to pass the authenticated userid on to Caucus, in a way that cannot be spoofed.  Here's how it works:

    1. The original application computes the MD5 hash of the string "userid,secret", where userid is the authenticated userid, and secret is some secret word.

    2. The original application writes a cookie called CAUCUSID, with the value "userid+hash", where hash is the 32 character hexadecimal encoding of the MD5 hash from the previous step.

    3. The Caucus configuration file swebd.conf contains the parameter setting: 
         Auth3Tag  secret

    4. The original application directs the user's browser to a URL of the form 
         http://localhost/sweb/swebsock/0/0/CC44/main/center.cml?0+0+x+x+x+x+x+x
      (See the caucus.html file to determine the precise URL, except that the above link must terminate in "center.cml" as shown.)

    5. Caucus decodes the userid from the CAUCUSID cookie, and does its own calculation of the MD5 hash, to ensure that the userid has not been spoofed.

    Note that you may completely disable this method by providing an Auth3Tag without a value, in swebd.conf.

In all three methods, when a user is authorised, their userid is provided by the $userid() function (inside a CML page).

The rest of this page describes the functions that are used to provide and extend cookie-based authentication.

$auth_method()        {protected}
Evaluates to a number that indicates the authentication method currently in use (as described above):
    0 = None (not authorised)
    1 = Basic authentication (http_remote_user)
    2 = Session-cookie based authentication
    3 = External application CAUCUSID cookie

$auth_cookie (userid [path])        {protected}
For authentication method 2 only.  Once the user has passed the 'login' page described above, use $auth_cookie() to generate the proper cookie(s) and send them to the browser. 

The call to $auth_cookie() should follow a "Location:" or "Content-type" HTTP header directive, but should appear before the blank line that signals the end of the directive.

Userid is the user's userid.  Path is the URL directory path for which the cookie applies; a typical value would be the string "/$(sweb)/swebsock", which means the cookie is good for any page in Caucus, regardless of interface directory.

Note: you may also call $auth_cookie without arguments to "log out" -- it sets the Caucus cookies to appropriate "garbage" values that un-authenticate, so to speak, the user.

$auth_pw ([password])        {protected}
For authentication method 2 only.  $auth_pw() provides a way to save and retrieve the user's password for future use, such as implementing "single-signon" with another web tool from inside Caucus.

Call $auth_pw (password) to save the user's password immediately after verifying (authorising) it.  This stores the password in the server's memory, but not on disk, and in a way that is not accessible by Caucus users (even if they are allowed to put CML text in their items and responses).

Call $auth_pw() (without an argument) to get the saved password (as the value of the function).