cas-server-2.0.12 README

This is a Wiki representation of the README file included with cas-server-2.0.12.

CAS 2.0 Server Distribution
Copyright (C) 2002-2004, Yale University
Original author: Shawn Bayern <shawn.bayern@yale.edu>
Current maintainer: Drew Mazurek

Manifest

This distribution contains the CAS 2.0 server – that is, the web application that authenticates users, provides CAS tickets, and validates these tickets. The CAS 2.0 server is written entirely in Java and is deployable in any compliant Servlet 2.3 container (e.g., Tomcat). See below for installation instructions.

In most environments, you'll also be interested in the CAS clients we provide for many platforms. The clients are available in a separate distribution ('casclient'), available from http://www.yale.edu/tp/cas. This site also contains general information about CAS and specific white papers that cover CAS's architecture. Note that while the CAS server requires a Java Servlet container, the CAS protocol is open and accessible from most modern platforms.

Installing the CAS Server

CAS is deployed as a web application compliant with the Servlet 2.3 standard. This means that your goal when building CAS is to produce a .WAR (web-application archive) file that can be deployed into a compliant container (such as Tomcat 4.x).

Building CAS is straightforward. Simply use the 'build.xml' (Ant script) in the root directory of this distribution. That is, once you've expanded this package and installed Ant, you can simply type

ant dist

with the CAS distribution's root directory as your current working directory. This command does three things:

1. It compiles all the Java source code in 'src' to binary Java class files in 'build'
2. It produces a .JAR file containing these classes, and installs it into the appropriate directory under 'web'.
3. It then produces a .WAR file from the contents of the 'web' directory; it places this .WAR file in the 'lib' directory.

You can then deploy the lib/cas.war file directly into your servlet container, or if your container lets you install an expanded web application, you can simply provide the contents of the 'web' directory to
your container. (To make this concrete, if you're using Tomcat 4.x, you can either (1) copy cas.war to Tomcat's 'webapps' directory, or (2) copy all of the files in 'web' to a subdirectory of 'webapps' called, say, 'cas'.)

Customizing the CAS Server

Your authenication handler

Out of the box, this distribution produces a CAS server with a dummy authenticator: the CAS server you install will authenticate any username as long as the username matches the password. (So you can log in as 'test' using the password 'test', but the password 'demo' will fail for that account.)

Of course, you'll want to modify the CAS server to use a password-validation scheme appropriate to your site. To support pluggable password-validation providers, CAS offers two interfaces, which you can find in the

edu.yale.its.tp.cas.auth

package (source for which is located under the 'src' directory in this distribution). These two interfaces are as follows:

PasswordHandler:

PasswordHandler is used when you want to validate username/password combinations. This would be appropriate for validating Unix users, for instance, and it can work with Kerberos and LDAP installations.

The interface provides a single method:

      /**
       * Authenticates the given username/password pair, returning true
       * on success and false on failure.
       */
      boolean authenticate(javax.servlet.ServletRequest request,
                           String username,
                           String password);

To provide your own password-validation logic, simply write a Java class that implements this (edu.yale.its.tp.cas.auth.PasswordHandler) interface and returns 'true' or 'false' appropriately. See below for information on how to 'install' this class – that is, how to make CAS aware of it.

TrustHandler

TrustHandler is used with more complex authentication schemes, such as situations where you have a J2EE server that handles authentication or, in general, any environment where simple form-acquired usernames and passwords aren't appropriate. I suspect that most environments will use PasswordHandler, but the TrustHandler interface is provided for extensibility. Instead of providing logic that accepts a username and password and determines whether they're correct, TrustHandler lets you provide logic that determines an authenticated username from whatever information it wants to acquire through a ServletRequest object:

/**
 * Allows arbitrary logic to compute an authenticated user from
 * a ServletRequest.
 */
 String getUsername(javax.servlet.ServletRequest request);

"Installing" your authentication handler

Whichever of these two classes you implement, you will need to install your class into the CAS server – that is, to make the CAS server aware that your new class is the one that it should use when authenticating
users.

CAS is configured in this regard (and many others) via the deployment descriptor (web.xml file) inside the web/WEB-INF directory under this distribution. Be sure to edit this file before running 'ant dist' and
producing your deployable WAR file.

The web.xml file provides several configurable options (more stricly, some "context-initialization parameters"). For more information on the structure of web.xml files generally, see the Servlet 2.3 specification. For our purposes, you'll simply need to know the properties that CAS expects to be set:

edu.yale.its.tp.cas.authHandler

The name of the class (implementing either PasswordHandler or TrustHandler) that you have written to provide authentication logic to CAS. (E.g., "edu.myuniversity.AuthProvider").

Other configuration

The web.xml provides configuration options other than what class to use as your authentication handler.

edu.yale.its.tp.cas.grantingTimeout

The timeout for ticket-granting tickets, in seconds. Ticket-granting tickets (TGCs in the architectural CAS documents) will last this long before being expired for inactivity. (The default is 7200, or two hours. Note that the ticket-granting ticket is only "used" when a user logs into an application anew; this calls for a longer timeout than the typical 20 minutes associated with many individual web applications.)

edu.yale.its.tp.cas.serviceTimeout

The inactivity timeout for service tickets (STs and PTs). This is expected to be quite small; the default is 300 seconds.

URLS

• edu.yale.its.tp.cas.serviceValidate
• edu.yale.its.tp.cas.loginForm
• edu.yale.its.tp.cas.genericSuccess
• edu.yale.its.tp.cas.redirect
• edu.yale.its.tp.cas.serviceSuccess
• edu.yale.its.tp.cas.confirmService
• edu.yale.its.tp.cas.logoutPage

Pointers to various URLs within the CAS application that are used by CAS to redirect the user appropriately depending on what CAS is trying to accomplish (e.g., returning the user to a web application, logging the user in, and so on).

Some of these URLs represent servlets provided by CAS that are registered by the default web.xml provided with this distribution. The rest of the URLs represent JSP pages in the distribution's 'web' directory.

The remaining items in web.xml are structural and should generally be left untouched.

When you implement PasswordHandler, you can use CAS's existing login form or modify the relevant JSP page (login.jsp) at will. This page is not used for TrustHandler.

The CAS login URL (to which applications should redirect users requiring authentication) is, by default, "/login" within the deployed CAS webapp. For instance, if you were to deploy to a server running at localhost on port 8080 and you named the application 'cas' (or deployed cas.war directly), the login URL would be

	http://localhost:8080/cas/login

The default validation URL, similarly, would be

	http://localhost:8080/cas/serviceValidate