Configuring uPortal to use CAS

uPortal 4 is shipped with a default CAS authentication configuration that uses a bundled CAS server. This CAS server is included in the uPortal build and is deployed to the same servlet container as uPortal.

The required CAS configuration is contained in two filters and filter mappings in the portal's web.xml and in the security.properties file. When any of the following configuration elements changes, the CAS configuration will need to change as well:

• server hostname
• server port
• SSL/non-SSL
• application context name change

To update the CAS authentication configuration, look for all values of "localhost" in the "CAS Validate Filter" element of web.xml. Each URL will need to be sensibly updated to match either the CAS or uPortal installation. The "logoutRedirect.root" and "org.jasig.portal.channels.CLogin.CasLoginUrl" properties of security.properties will also need modification. More information on the configuration filter parameters can be found in the CAS documentation.

Configuration Options

Option 1: Using the uPortal Bundled CAS Server
Option 2: Using an External CAS Server

Option 1: Using the uPortal Bundled CAS Server

The code below provides an example of changing the default "http://localhost:8080" installation to a real domain, mapped by Apache over SSL at "https://portal.school.edu".

Step 1: Edit filters/local.properties

 1. In the filters folder, locate the default local.properties file (uPortal-4.x/filters) and configure the CAS Server Configuration. Replace localhost:8080 with your server name.

# HSQL Configuration
environment.build.hsql.port=8887

# Database Connection Settings (Uncomment the Maven Filters section in rdbm.properties)
environment.build.hibernate.connection.driver_class=org.hsqldb.jdbc.JDBCDriver
environment.build.hibernate.connection.url=jdbc:hsqldb:hsql://localhost:${environment.build.hsql.port}/uPortal
environment.build.hibernate.connection.username=sa
environment.build.hibernate.connection.password=
environment.build.hibernate.dialect=org.hibernate.dialect.HSQLDialect

# uPortal server configuration properties
environment.build.uportal.server=localhost:8080
environment.build.uportal.protocol=http
environment.build.uportal.context=/uPortal
environment.build.uportal.email.fromAddress=portal@university.edu

# CAS server configuration properties
environment.build.cas.server=localhost:8080
environment.build.cas.protocol=http

Step 2: Edit the security.properties file

You can edit the security.properties file (uPortal-4.x/uportal-war/src/main/resources/properties/security.properties) to update the Logout redirect string, by default it points to the uPortal Login page. Also, if you are interested in turning on the clearPass feature you can uncomment the  "org.jasig.cas3.extensions.clearpass..." line of code. 

## This is the factory that supplies the concrete authentication class
root=org.jasig.portal.security.provider.UnionSecurityContextFactory
root.cas=org.jasig.portal.security.provider.cas.CasAssertionSecurityContextFactory
#root.cas=org.jasig.cas3.extensions.clearpass,integration.uportal.PasswordCachingCasAssertionSecurityContextFactory 
root.simple=org.jasig.portal.security.provider.SimpleSecurityContextFactory

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

## 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=${environment.build.cas.protocol}://${environment.build.cas.server}/cas/logout?url=${environment.build.uportal.protocol}://${environment.build.uportal.server}${environment.build.uportal.context}/Login


## This is the factory that supplies the concrete authorization class
authorizationProvider=org.jasig.portal.security.provider.AuthorizationServiceFactoryImpl


## 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=${environment.build.cas.protocol}://${environment.build.cas.server}/cas/login?service=${environment.build.uportal.protocol}://${environment.build.uportal.server}${environment.build.uportal.context}/Login


## URL of the CAS cleartext password service
#org.jasig.cas3.extensions.clearpass.integration.uportal.PasswordCachingCasAssertionSecurityContextFactory.clearPassCasUrl=${environment.build.cas.protocol}://${environment.build.cas.server}/cas/clearPass


###
...

Step 3: Rebuild/Redeploy uPortal

ant clean deploy-war

Step 4: Restart Tomcat

Restart your tomcat servlet container to activate the modification.

Option 2: Using an External CAS Server

Configuring uPortal for an external CAS service is essentially the same. Once the portal is configured against an external CAS server, you may wish to remove the bundled CAS installation.

Steps 1 and 2: As Above

Configuration uPortal to authenticate to an external CAS server will require modifying the web.xml and security.properties files shown above to match the new CAS URL.

Step 3: Remove Bundled CAS Dependencies from Maven POM Files

To prevent CAS from being deployed by the ant deploy-ear task, perform the following changes:

1. Remove the line <module>cas</module> from uPortal-4.x/uportal-portlets-overlay/pom.xml.

   <modules>
           <module>BookmarksPortlet</module>
   	<!-- comment out the cas module below -->
           <!-- module>cas</module -->
           <module>cas-proxy-test-portlet</module>
           ...
   </modules>

2. Remove the CAS dependency and webModule elements from uPortal-4.x/uportal-ear/pom.xml.

   <dependency>
               <groupId>org.jasig.portal.portlets-overlay</groupId>
               <artifactId>cas</artifactId>
               <version>${project.version}</version>
               <type>war</type>
   </dependency>

Step 4: CAS Server 3.5.3+

CAS Server 3.5.3 changed the default value of 'AllowedToProxy' to false.  Make sure your uPortal service that is registered with the CAS service registry is allowed to execute proxy authentication. Consult CAS docs for your appropriate version.  If this is not done, on Login you will see an error similar to the following in portal.log:

ERROR [http-bio-8080-exec-20641] web.ExceptionLoggingFilter.[] 2015-01-29 11:27:40,956 - uPortal: unhandled exception 'org.jasig.cas.client.validation.TicketValidationException: 
service.not.authorized.proxy' for URL=/uPortal/Login?ticket=ST-144-go3as7Kx5dyg05gKf45Z-cas
javax.servlet.ServletException: org.jasig.cas.client.validation.TicketValidationException: service.not.authorized.proxy

Step 5. Rebuild/Redeploy uPortal

ant clean deploy-war

Step 6: Restart Tomcat

Restart your tomcat servlet container to activate the modification.