Page Comparison

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

Binary dependencies

CASifying uPortal requires the Java CAS Client. 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.

...

...

You should not need to change the Java CAS Client version, however, if you do,edit the main pom.xml as follows

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

<!-- 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. The Yale 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 23.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.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>httpsvalue>http://www.ja-sig.orgyour.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.yourschoolserver.edu:8080<com</param-value>
   </init-param>
</filter>  <filter> <filter-name>CAS Receipt Cacher</filter-name>
<filter-class>edu<init-param>
      <param-name>edu.yale.its.tp.cas.client.filter.StaticCasReceiptCacherFilter<proxyCallbackUrl</filterparam-class>name>
</filter>  <filter-mapping> <filter-name>CAS Validate Filter</filter-name> <url-pattern>/Login</url-pattern><param-value>http://yourportal.server.com/uPortal/CasProxyServlet</param-value>
   </filterinit-mapping>param>

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

...

</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

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%2FLoginSet 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

Cleaning up

Remove the dependency for the embedded CAS server by deleting the uportal-portlets-overlay/cas directory.

Deploying your changes

ant clean deploy-war

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.