CASValidateFilter

Before you try to use the CASValidateFilter, consider whether the basic CASFilter would better suit your needs. CASFilter provides a standard distribution of the most frequently needed CASification behaviors for Java webapps.

CASValidateFilter came into existence to provide a standard distribution of a more flexible CAS authentication filter. CASValidate filter does less.

Configuring CASValidateFilter

Just a few lines of XML need to be added to your web application's deployment descriptor (web.xml):

<web-app>
  ...
   <filter>
      <filter-name>CAS Validate Filter</filter-name>       
      <filter-class>edu.yale.its.tp.cas.client.filter.CASValidateFilter</filter-class>
      <init-param>
        <param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name>
        <param-value>https://secure.its.yale.edu/cas/serviceValidate</param-value>
      </init-param>
      <init-param>
        <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
        <param-value>hkg2.cis.yale.edu:8080</param-value>
      </init-param>
      <init-param>
        <param-name>edu.yale.its.tp.cas.client.filter.proxyCallbackUrl</param-name>
        <param-value>https://hkg2.cis.yale.edu/uPortal/CasProxyServlet</param-value>
      </init-param>
   </filter>

  <filter-mapping>
    <filter-name>CAS Validate Filter</filter-name>
    <url-pattern>/Login</url-pattern>
  </filter-mapping>
  ...
</web-app>

In this case, the filter will perform ticket validation on the URL /webapp/Login if a service ticket is present. Unlike CASFilter, CASValidateFilter will just let the request right through without performing any CAS authentcation if a service ticket is not presented on the request.

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

You can specify other initialization parameters to configure the behavior of the filter:

Required CASValidateFilter init-params

init-param name

usage

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. When you use this parameter, CASValidateFilter will use the request path as the service URL, being sure to use the configured serverName as the host.

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 CASValidateFilter

Once the user has logged into your application through the filter, the application may access the user's NetID 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.

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

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 CASValidateFilter

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.