01 CAS Authentication for the Impatient

Binary dependencies

CASifying uPortal requires the Java CAS Client. The necessary dependencies are included with uPortal. You should not need to change the Java CAS Client version, however, if you do,edit the main pom.xml as follows

<!-- Project Dependency Version Properties -->
<casclient.version>2.2.0-M2</casclient.version>

CAS Server dependencies

Of course, to CAS authenticate to your uPortal, you'll need a CAS server to use to do the authentication. uPortal 3.x comes with an embedded CAS 3.x server, these instructions are for using your own CAS server. If you'd like to use the embedded CAS server, please see 05 Exercise - Configuring CAS to use another authentication handler

The Java CAS Client library shipping with uPortal 3.x will work with any CAS server implementing CAS 3.X or below.

uportal-war/src/main/webapp/WEB-INF/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. These will already be declared for you. You'll just need to adjust them to your specific environment.

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.

<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>http://your.cas.server.com/cas/serviceValidate</param-value>
   </init-param>
   <init-param>
      <param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
      <param-value>yourportal.server.com</param-value>
   </init-param>
   <init-param>
      <param-name>edu.yale.its.tp.cas.client.filter.proxyCallbackUrl</param-name>
      <param-value>http://yourportal.server.com/CasProxyServlet</param-value>
   </init-param>
</filter>

<init-param>
  <param-name>BROKEN_SECURITY_ALLOW_NON_SSL</param-name>
  <param-value>NOT_SECURE_DO_NOT_USE_THIS_SETTING_IN_PRODUCTION</param-value>
</init-param>

uportal-impl/src/main/resources/properties/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, and impersonation approach to authenticating users. You shouldn't need to change these settings unless you'd not like to have the other authentication approaches.

root=org.jasig.portal.security.provider.UnionSecurityContextFactory
root.cas=org.jasig.portal.security.provider.cas.CasFilteredSecurityContextFactory
root.simple=org.jasig.portal.security.provider.SimpleSecurityContextFactory
root.impersonation=org.jasig.portal.security.provider.ImpersonationSecurityContext$Factory

Also in security.properties, you need to tell uPortal what tokens (request parameters) to recognize and use. You also shouldn't need to change these unless your request tokens differ from the standard CAS.

## 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
principalToken.root.impersonation=ticket
credentialToken.root=password
credentialToken.root.cas=ticket

Set the login URL for the portal (it's important that you use HTTP encoding)

## Login URL, if specified the CLogin channel will display a Login link with
## this URL instead of the standard userName/password form.
org.jasig.portal.channels.CLogin.CasLoginUrl=http://your.cas.server.com/cas/login?service=https%3A%2F%2Fyourportal.server.com%2FLogin

Set the logout URL for the portal (it's important that you use HTTP encoding if your URL contains spaces, etc)

## Answers where the user will be redirected when log out occurs. Each security context can have one.
## (See comments in the LogoutServlet class)
## It would be better to escape the value of the url parameter, but since there are no parameters on the
## unescaped URL and since there are no further parameters on the logout URL, this does work.
logoutRedirect.root=http://your.cas.server.com/cas/logout?url=https://yourportal.server.com/Login

Your configuration of uPortal and CAS may be different so you may have to use https instead of http, or vice versa.

Cleaning up

Remove the dependency for the embedded CAS server by deleting the uportal-portlets-overlay/cas directory.  You will also need to edit the references that are made to the CAS directory.  Remove <module>cas</module> from pom.xml in the uportal-portlets-overlay and also the CAS webModule referenced in the pom.xml file found in the uportal-ear folder.

Deploying your changes

ant clean deploy-ear

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.