01 CAS Authentication for the Impatient

uPortal 2.5.2 and later ship with the client libraries and example configuration for using CAS.

This manual page is intended to be a quick guide for CASifying uPortal. It is current as of uPortal 2.6.0. It happens to be true that this configuration will also work in uPortal 2.5.2 and uPortal 2.5.3.

There are a number of ways to CASify a uPortal. You don't have to do it this way. The intent of this page is to clearly set forth one way to do it without a lot of distraction and fluff. You can read the rest of this manual to get more ideas about this and other approaches. When this page says things like "CASifying uPortal requires such and such", that's a simplification – there's an implicit "CASifying uPortal in this way requires such and such".

Binary dependencies

The necessary dependencies are included with uPortal. CASifying uPortal requires the Yale Java CAS Client .jar. This is included in uPortal's lib directory as

casclient-2.1.1.jar

The uPortal build.xml deploy target will deploy this .jar into the lib directory of the uPortal web application.

Before uPortal 2.6.0: build.properties file details

Prior to uportal 2.6.0, the uPortal build.xml finds that .jar as specified in build.properties

CAS client jar declared in build.xml

<property name="casclient.jar" value="lib/casclient-2.1.1.jar"/>

If there is no entry in build.properties declaring this .jar, the build falls back on the default of finding the .jar as "casclient-2.1.1.jar" in the uPortal lib directory, which is convenient since that's where it's included in the distribution. You don't need to change this unless you want to get the .jar from some other path, and you won't need to deal with this at all if you're using uPortal 2.6.0's more literate dependency discovery approach.

CAS Server dependencies

Of course, to CAS authenticate to your uPortal, you'll need a CAS server to use to do the authentication.

The Yale Java CAS Client library shipping with uPortal 2.6.x will work with any CAS server implementing the CAS 2.0 XML-style ticket validation protocol, including Yale CAS server 2.x releases, JA-SIG CAS server releases, and even the RubyCAS server. However, this library will not work with CAS 1.0 plaintext-style validation responses. A modest amount of development effort would be required to implement support for a CAS server under the legacy protocol.

web.xml configuration

CASifying uPortal is like CASifying other web applications. You need to declare the CasValidateFilter to detect and validate CAS tickets. Additionally, you need to declare the CAS Receipt Cacher filter as a bridge between the filter tier and the security provider API layer.

The filter is mapped over the /Login path because the CAS ticket is treated like other uPortal security credentials. You'd send your password to /Login if you were authenticating via password. You send your ticket to /Login to authenticate via CAS.

Declaring and mapping the necessary filters

<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://www.ja-sig.org/cas/serviceValidate</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
<param-value>yourportal.yourschool.edu:8080</param-value>
</init-param>
</filter>

<filter>
<filter-name>CAS Receipt Cacher</filter-name>
<filter-class>edu.yale.its.tp.cas.client.filter.StaticCasReceiptCacherFilter</filter-class>
</filter>

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

<filter-mapping>
<filter-name>CAS Receipt Cacher</filter-name>
<url-pattern>/Login</url-pattern>
</filter-mapping>

uPortal security properties configuration

uPortal's /Login behavior is configurable via a pluggable security context API and a security.properties configuration file. Here's what you include to get it to use CAS. What we're saying here is that we'd like to use both (the "union" of) the CAS filter approach and the simple username,password approach to authenticating users.

root=org.jasig.portal.security.provider.UnionSecurityContextFactory
root.cas=org.jasig.portal.security.provider.cas.CasFilteredSecurityContextFactory
root.simple=org.jasig.portal.security.provider.SimpleSecurityContextFactory

Also in security.properties, you need to tell uPortal what tokens (request parameters) to recognize and use.

## Answers what tokens are examined in the request for each context during authentication.
## A subcontext only needs to set its tokens if it differs from those of the root context.
principalToken.root=userName
credentialToken.root=password
credentialToken.root.cas=ticket

UI layer

With the filter in place and the security provider declared, uPortal is ready to accept CAS tickets. However, you need to get your users to actually interact with your CAS server to acquire and present CAS tickets. This is typically accomplished via a hyperlink or button on your portal that links to CAS specifying your portal as the desired "service" that users are to be sent back to on authentication.

To log into your CASified Portal, you follow a URL to your CAS server with the URL-encoded URL of your uPortal Login servlet as the "service" request parameter. Your uPortal login URL is something like: http://someschool.edu/uPortal/Login and your CAS server URL is something like https://secure.school.edu/cas/login and so the URL you should click to begin the login process is something like: https://www.ja-sig.org/cas/login?service=http%3A%2F%2Fsomeschool.edu%2FuPortal%2FLogin

Testing it

JA-SIG hosts a CAS server backed by Jira for user accounts. So you can create an account in JA-SIG Jira (you should be doing this anyway so you can comment on uPortal issues and post bugs and patches), create a user with the same name as your JA-SIG Jira account in your portal (or allow uPortal to auto-create accounts), and then you can try out using JA-SIG's CAS server to authenticate to your uPortal.