Java CAS client

Overview

The Yale Java CAS client includes Java objects for ticket validation and proxy ticket acquisition, servlets and filters implementing the client portion of the CAS protocol and suitable for "CASifying" a servlet path, a Java object for representing the results of a CAS authentication, and JSP tags for applying CAS authentication. This library is usable for implementing custom CAS functionality and for simply CASifying web applications by application of a filter, and forms the basis for Acegi and uPortal CAS support.

Downloading

The Java CAS client jar is available from ibiblio.

The entire distribution (including JavaDocs and documentation) is available from the downloads page.

Declaring Maven dependency:

    jar
    cas
    casclient
    2.1.1
    
       true
    
 

Using the Java CAS client

CASFilter

The CAS filter is the simplest way of CAS-protecting your Java Servlets application.

Basic CASFilter configuration

This is how you map the CASFilter in your web.xml to filterrequests for paths in your web application that begin with "requires-cas-authentication/":

  ...
  
 CAS Filter
 edu.yale.its.tp.cas.client.filter.CASFilter
    
       edu.yale.its.tp.cas.client.filter.loginUrl
       https://secure.its.yale.edu/cas/login
    
    
       edu.yale.its.tp.cas.client.filter.validateUrl
       https://secure.its.yale.edu/cas/serviceValidate
    
    
       edu.yale.its.tp.cas.client.filter.serverName
       your server name and port (e.g., www.yale.edu:8080)
    
 
 
 
    CAS Filter
    /requires-cas-authetication/*
 
  ...
  

If instead you wanted every path in your web application to require CAS authentication, you would map the filter to the /* URL pattern:

    CAS Filter
    /*
  

The serverName initialization parameter does not require a port number if you are using the standard HTTP port (80).

Required CASFilter init-params

init-param name usage edu.yale.its.tp.cas.client.filter.loginUrl The URL whereat CAS offers its Login page. e.g. https://secure.its.yale.edu/cas/login edu.yale.its.tp.cas.client.filter.validateUrl The URL whereat CAS offers its service ticket or proxy ticket validation service. e.g. https://secure.its.yale.edu/cas/serviceValidate or https://secure.its.yale.edu/cas/proxyValidate. Must be a proxyValidate service if you intend to accept any proxy tickets. edu.yale.its.tp.cas.client.filter.serverName This parameter specifies the server name and port of the service being filtered (not of the CAS Server itself). E.g., www.yale.edu:8080 Either this parameter or the serviceUrl parameter must be set. edu.yale.its.tp.cas.client.filter.serviceUrl This parameter replaces the serverName parameter above. It becomes the URL that CAS redirects to after login. If you have one specific point of entry to your web application and you want all logins to proceed through that page, you would specify the full URL of that page here. Either this parameter or the serverName parameter must be set.

Optional CASFilter init-params

init-param usage edu.yale.its.tp.cas.client.filter.proxyCallbackUrl to obtain a Proxy Granting Ticket and thereby have your application proxy authentication to other services, you‘ll need to specify an http: URL where you‘d like PGT, PGTIOU pairs sent. This will typically be a URL you‘ve mapped to an instance of the ProxyTicketReceptor servlet. edu.yale.its.tp.cas.client.filter.authorizedProxy to allow the filter to accept proxy tickets, you need to specify valid proxies through which the authorization must have proceeded. This initialization parameter accepts a whitespace-delimited list of valid proxy URLs. Only one URL needs to match for the login to be successful. Note that if you do want to accept proxy tickets, you will have to change the validateUrl above to proxyValidate rather than serviceValidate edu.yale.its.tp.cas.client.filter.renew if set to the string, true, this is the equivalent of authenticating a ticket with renew=true passed as a parameter. This may be used for high-security applications where the user must enter his/her credentials again before accessing the filtered URLs. edu.yale.its.tp.cas.client.filter.wrapRequest if set to the string "true" the CASFilter will wrap the request such that calls to getRemoteUser() return the authenticated username.

Consuming the results of CASFilter

Once the user has logged into your application through the filter, the application may access the user‘s name through the session attribute, edu.yale.its.tp.cas.client.filter.user, or if you import edu.yale.its.tp.cas.client.filter.CASFilter in your JSP or servlet, simply CASFilter.CAS_FILTER_USER.

Accessing the authenticated username from Java

// either of these will work:
 session.getAttribute(CASFilter.CAS_FILTER_USER);
 session.getAttribute("edu.yale.its.tp.cas.client.filter.user"); 

Accessing the authenticated username via JSTL

Additionally, the client application may access a CASReceipt JavaBean-style object which exposes the username as well as additional information about the successful authentication, in the session attribute edu.yale.its.tp.cas.client.filter.receipt .

// either of these will work:
 session.getAttribute(CASFilter.CAS_FILTER_RECEIPT);
 session.getAttribute("edu.yale.its.tp.cas.client.filter.receipt");

Session attributes set by CASFilter

Session attribute usage edu.yale.its.tp.cas.client.filter.user String representing the authenticated NetID edu.yale.its.tp.cas.client.filter.receipt CASReceipt representing the results of CAS authentication. Use this object to programmatically access the proxy chain, whether the authentication was required to have been by presentation of primary credentials, etc.

CAS Tag Library

The CAS Tag Library is a another way to authenticate users‘ access to JSP pages. JSP Tags cannot be used in servlets, so if you need CAS protection within a servlet environment, you can use either the CAS Filter or the CAS Java objects (see below); the former is recommended.

To use the tag library, once casclient.jar is installed in your web application‘s /WEB-INF/lib directory, you need to add the following to the top of a JSP page you wish to protect:

<%@ taglib uri="http://www.yale.edu/its/tp/cas/version2" prefix="cas"%>
    
    https://secure.its.yale.edu/cas/login
    https://secure.its.yale.edu/cas/proxyValidate
    https://authorized-proxy1
    https://authorized-proxy2
  ...
    http://service-url
 
 ...
 
 
    
       
Welcome, <%= session.getAttribute("netID"); %>!

    
  

The user will not see any part of the page past the tags until he/she has logged in. If the user hasn‘t logged in yet, a redirect to the CAS login page will be performed.

Also provided with the CAS Tag Library is a logout tag:

<%@ taglib uri="http://www.yale.edu/its/tp/cas/version2" prefix="cas" %>
 <%-- first destroy the web application‘s session --%>
 <% session.invalidate(); %>
 <%-- then logout of CAS --%>
   logoutUrl="https://secure.its.yale.edu/cas/logout" /> 

CAS Java Objects

You may also authenticate users "manually" using the CAS Java objects. In this case, you would instantiate a new ServiceTicketValidator or ProxyTicketValidator. Notice that in the example below, the page already expects to receive a ticket parameter (this is the servlet that CAS returned to after the user logged in). If this servlet was accessed directly by a user, it would need to check that the request parameter, ticket, was not null. If it was null, the servlet would need to redirect to the CAS login page manually.

ServiceTicketValidator:

import edu.yale.its.tp.cas.client.*;
 
 ...
 String user = null;
 String errorCode = null;
 String errorMessage = null;
 String xmlResponse = null;
 
 /* instantiate a new ServiceTicketValidator */
 ServiceTicketValidator sv = new ServiceTicketValidator();
 
 /* set its parameters */
 sv.setCasValidateUrl("https://secure.its.yale.edu/cas/serviceValidate");
 sv.setService(urlOfThisService);
 sv.setServiceTicket(request.getParameter("ticket"));
 
 /*
  * If we want to be able to acquire proxy tickets (requires callback servlet to be set up 
  * in web.xml - see below)
  */
 
 String urlOfProxyCallbackServlet = "https://portal.yale.edu/CasProxyServlet";
 
 sv.setProxyCallbackUrl(urlOfProxyCallbackServlet);
 
 /* contact CAS and validate */
 sv.validate();
 
 /* if we want to look at the raw response, we can use getResponse() */
 xmlResponse = sv.getResponse();
 
 /* read the response */
 
 // Yes, this method is misspelled in this way 
 // in the ServiceTicketValidator implementation. 
 // Sorry.
 if(sv.isAuthenticationSuccesful()) {
  user = sv.getUser();
 } else {
  errorCode = sv.getErrorCode();
  errorMessage = sv.getErrorMessage();
  /* handle the error */
 }
 
 /* The user is now authenticated. */
 
 /* If we did set the proxy callback url, we can get proxy tickets with: */
 
 
 String urlOfTargetService = "http://hkg2.its.yale.edu/someApp/portalFeed";
 
 String proxyTicket = ProxyTicketReceptor.getProxyTicket(
  sv.getPgtIou(),urlOfTargetService); 

ProxyTicketValidator

The proxy ticket validator is almost identical, except it allows you to validate service tickets or proxy tickets. This class contains one additional method, getProxyList(), which accesses the list of URLs through which the authentication was proxied.

import edu.yale.its.tp.cas.client.*;
 
 ...
 
 String user = null;
 String errorCode = null;
 String errorMessage = null;
 String xmlResponse = null;
 List proxyList = null;
 
 /* instantiate a new ProxyTicketValidator */
 ProxyTicketValidator pv = new ProxyTicketValidator(); 
 
 /* set its parameters */
 pv.setCasValidateUrl("https://secure.its.yale.edu/cas/proxyValidate");
 pv.setService(urlOfThisService);
 pv.setServiceTicket(request.getParameter("ticket")); 
 
 /*
  * If we want to be able to acquire proxy tickets 
  * (requires callback servlet to be set up 
  * in web.xml -- see below)
  */
 
 String urlOfProxyCallbackServlet = "https://portal.yale.edu/CasProxyServlet";
 
 pv.setProxyCallbackUrl(urlOfProxyCallbackServlet); 
 
 /* contact CAS and validate */
 pv.validate();
 
 /* if we want to look at the raw response, we can use getResponse() */
 xmlResponse = pv.getResponse(); 
 
 /* read the response */
 // Yes, this method is misspelled in this way 
 // in the ServiceTicketValidator implementation. 
 // Sorry.
 if(pv.isAuthenticationSuccesful()) {
  user = pv.getUser();
  proxyList = pv.getProxyList();
 } else {
  errorCode = pv.getErrorCode();
  errorMessage = pv.getErrorMessage();
  /* handle the error */
 }
 
 /* The user is now authenticated. */
 
 /* If we did set the proxy callback url, we can get proxy tickets with this method call: 
  */
 
 String urlOfTargetService = "http://hkg2.its.yale.edu/someApp/portalFeed";
 
 String proxyTicket =
  edu.yale.its.tp.cas.proxy.ProxyTicketReceptor.getProxyTicket(
  pv.getPgtIou(),urlOfTargetService); 

ProxyTicketReceptor

In order to obtain proxy tickets, the proxy callback listener must be set up as a servlet in the application‘s web.xml:

 
  ...
  
  ProxyTicketReceptor
  edu.yale.its.tp.cas.proxy.ProxyTicketReceptor
  
 
 
  ProxyTicketReceptor
  /CasProxyServlet
  
  ...
 
  

Alternatives to using the Java CAS client

Acegi

Acegi provides a more general abstraction for Java application security, including authentication and authorization. It supports CAS as one of several options for authentication mechanism. Consider using the Acegi abstraction rather than the lower-level abstractions offered by the Java CAS client.

Fronting your Java web application with Apache

You can configure Apache to apply CAS authentication (by such means as MOD_CAS) and then configure the Tomcat connector to convey the REMOTE_USER and your Java web application to receive this information and use it.