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

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

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: 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: 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);

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").

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.

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