CAS Dispatcher

Introduction

The CAS Dispatcher is designed to allows the cohabitation of many Central Authentication Server ( CAS - http://www.yale.edu/tp/auth/) in a global authentication infrastructure.

The CAS Dispatcher was build to offer an alternative to the Danish LDAP based authentication infrastructure (see DEF Distributed Authentication System - CAS Dispatcher for general introduction to the problems and solution proposed).

Requirements

This package require Perl v5.6.1 minimum. It also requires the following Perl modules:

• IO::Socket::SSL for CAS validation.
• XML::XPath for info_dtu.
• Net::LDAPS for info_ldap.

Finally, since this package does transparent CAS validation, it requires a HTTPS server, preferably Apache. HTTPS is a requirement of the CAS validation process although the validation itself can work without SSL.

Download

The latest version of CAS dispatcher is 1.2 and can be downloaded from: http://toolxite.net/cas_dispatcher/cas_dispatcher.1.2.tar.gz

Installation

The simplest installation method is to unpack the package in in the HTTPS server CGI script directory (e.g. cgi-bin). This allows all scripts (login, login_reply and validate) to be used directly from the unpacked distribution.

If you HTTP server supports symbolic links, you can create a version independent link after unpacking the package to avoid URL changes for each new version.

Example installation:
# wget http://toolxite.net/cas_dispatcher/cas_dispatcher.1.2.tar.gz
# cd /usr/lib/cgi-bin/
# tar xzf ~/cas_dispatcher.1.2.tar.gz
# ln -s cas_dispatcher.1.2 cas_dispatcher

Basic CAS function

After installation, you need to configure the server.conf file to include all CAS servers part of your infrastructure. Once this is done, you can start using the CAS dispatcher as a standard CAS server. For the example above on the toolxite.net server, you could use the following URLs:

• CAS login:
  https://toolxite.net/cgi-bin/cas_dispatcher/login
• CAS validation:
  https://toolxite.net/cgi-bin/cas_dispatcher/validate

In it's basic setup, the CAS dispactcher will behave like an ordinary CAS server, except that the user will be prompted for selection of CAS server if one as not been already selected. The other small difference is that the validate no reply, which normally does not include a second line, can optionally contain an error message as the second line. In that case, the no specifies that a validation error occured (described in the message), rather than a simple invalid ticket.

Please remember that the service argument used for login and validate should be strictly the same, the smallest difference will lead to a validation error.

Extra validation options

The CAS dispatcher validation proceedure allows for extra parameters which will generate an extra lookup and return extra user information.

Information

Request for extra user information information is triggered by the info CGI parameter (info=1). For info to work, the servers.conf file should include a cas_info entries with a info script URL for the CAS server in use. Generally, it is a bad idea to use info if not all servers in servers.conf include a cas_info entry. Requesting info from a CAS server which does not provide it will cause the validation to fail.

When a cas_info URL exists, validate will call that URL with the parameter id containing the CAS login ID of the user being validated. This CGI script should return any of the following fields:

• id: the user ID which can be the same as CAS login ID or different
• name: the user name, for information purpose
• email: the user email address
• inst: the user organisation/department name
• type: the user type

So far, no formal values or formats have been defined for these fields but this may be wise for participants in a CAS network to agree on this.

These fields are return by the info script one per line with the field name followed by one or more spaces and the field value. Validate returns them ASIS after the first two standard line of CAS validate reply. See Package content, servers.conf and validate for more information.

Mapping

In some cases, the CAS login ID return by validate is not the ID needed for your service. For example, Dspace needs email addresses as IDs and not CAS login IDs. In this case, it is possible to use the map argument to validate, so that the CAS login ID in the validate reply (second line) is replaced with a different value. For example, use the map=email argument, will replace the CAS login ID with the email address. Using the map argument will automatically automatically invoke the info mechanism described above. See Package content, servers.conf and validate for more information.

Package content

The CAS Dispatcher package includes the following files:

• CAS.pm
  A simple CAS validation package. This package uses the mHTTP module, included this distribution.
• Dispatcher.pm
  The core dispatching module.
• doc/
  This and other documentation.
• info_dtu
  The information CGI script used at DTU for access to the SOAP interface of the DTU User Database. This script makes use of the DTU_userdb package not included in this distribution, but available at http://toolxite.net/DTU_userdb/.
• info_ldap
  An example information CGI script for use with an LDAP server in the current DEF LDAP infrastructure. This script requires the Net::LDAPS package as well as a valid certificate (cert, key and ca) for use in the DEF LDAP infrastructure.
• login
  The CAS login CGI script. If the user has not yet selected a CAS server, the HTML form in login.html will be returned with a list of CAS server defined in servers.conf. Just like a standard CAS login, this CGI script expects the parameter service. This script modifies the service paramter to make sure that the CAS server reply will pass through the CAS Dispatcher (login_reply). The optional parameter lang can be used to use a language specific interface, if defined.
• login.html
  The HTML page present to the end-user for selection of a CAS server. This pages contains a <dispatcher:cas_server_select/> tag which is replaced by a select form element with a list of CAS servers defined in servers.conf.
• login_reply
  The CGI script used by the CAS server for returning the ticket to the original servicer provider. This script accepts the parameter ticket which it modifies to add a CAS server ID needed during validation.
• mHTTP.pm
  A very basic HTTP module used for the communication with the CAS servers and with the information scripts.
• servers.conf
  The CAS servers configuration file used by the login and validate CGI scripts. Each line in the configuration is composed of a code (CAS server internal ID), a field-name and a value.
  
  e.g. dtu   name   DTU
  
  The code can only contain characters a-z, 0-9 and underline (_).
  Valid field-name are:
  • name
    The name presented to the user at login.
  • cas_login
    URL for CAS login.
  • cas_validate
    URL for CAS validation.
  • cas_info
    URL for user information service.
  • login_id
    One of id, name, email, inst or type, though only the first three make sence. This can be used to avoid a mapping using the info script when the server already returns the correct ID. For example is a server has login_id email and validate is called with map=email, no real mapping will be done since the dispatcher assumes that server already returns an email as login ID.
  All fields can have a language appended (e.g. name.eng or name.dan), the value of that language code is defined in the lang CGI parameter.
• validate
  The CAS validation CGI script. This script will do a transparent validation towards the CAS server used for user login and return the standard status (yes or no) and the user login ID in case of yes status. In addition to the standard reply, it will sometime return a second line containing an error message in case of no status. This allows the calling program to know that the no does not indicate an invalid ticket but an error during the ticket validation process. This script expect the two standard CGI parameters: service, which should be the same as used in login, and ticket which was the login ticket returned though the CAS Dispatcher. Furthermore, the script also accepts the parameter info=1 which will invoke the info CGI script defined for that CAS server and returned extra fields after the standard two first lines. These information fields are id, name, email, inst and type. All fields are optional, they are returned one per line with the label given above a space and the value for that field.

  yes
  testuser
  id testuser
  name Doe, John
  email john@world.org
  inst world
  type staff
  

  Finally, a map argument can be given to map the CAS user ID, second line, to one of the info fields. For example, map=email for the record above will give:

  yes
  john@world.org
  id testuser
  name Doe, John
  email john@world.org
  inst world
  type staff
  

  where the second line is replaced by the email.