Skip to end of metadata
Go to start of metadata
Table of Contents

New CAS documentation site

Icon

CAS documentation has moved over to apereo.github.io/cas, starting with CAS version 4.x. The wiki will no longer be maintained. For the most recent version of the documentation, please refer to the aforementioned link.

Icon

For configuration instructions, refer to the Installation Instructions section below on this page.

 

Background

Purpose

To enable single sign-on into some legacy application it may be necessary to provide them with the actual cleartext password. While such approach inevitably increases security risk, a number of institutions found it to be a "necessary evil". The original version of ClearPass was developed by Unicon for Sacramento State. The first official release as a CAS extension was sponsored by the Unicon Cooperative Support program.

Architecture

A service may obtain cleartext credentials for an authenticated user by presenting a valid proxy ticket obtained specifically for the CAS cleartext extension service end-point (ClearPass).

Upon receiving the request, ClearPassController ensures that the following validation criteria are met:

  1. The proxy ticket was obtained for the URL specifying location of the ClearPass service
  2. The proxy is valid according to standard CAS spec
  3. The proxy ticket is indeed a proxy ticket, not a service ticket
  4. Each member of the proxy chain has been given explicit permission to receive cleartext credentials

    Icon

    Tickets issued for a ClearPass response are validated in the same way you would access a traditional proxied service from say your portal! ClearPass ensures this by just being another CAS Client!

    Upon successful validation the ClearPass service provides credentials in the following response:

    If the validation fails, the traditional response is a 403 Status code being returned. If there are failures for any other reason other than authorization, the following error response is returned:

Source Control

Source Code Location

As of CAS v3.5, the ClearPass extension is available as part of the CAS codebase in form a separate Maven module. The source code is located at:

ClearPass in CAS v3.5

Previous versions of the ClearPass extension may also be found at the following Github repository:

ClearPass prior to CAS v3.5

Accessing the Source

As of CAS v3.5, you may retrieve the ClearPass extension when you clone the CAS Github project using the following command:

Cloning the CAS Github project for ClearPass

Previous version of the ClearPass extension may be retrieved/cloned using the following comment:

Cloning ClearPass prior to CAS v3.5

Issue Tracker

The project currently maintains a project in the Jasig Issue Tracker:

Building

Building ClearPass using Maven2

Building ClearPass via the Maven2 system is simple. From within the PROJECT_HOME directory, execute the following command:

  • "clean" is optional and ensures that all previous artifacts have been cleaned up before generating new ones.
  • "package" generates the appropriate packages for the sub-module (i.e. war, jar, etc.)
  • "install" makes the sub-modules available from the local repository such that other sub-modules can see the new ones.

Updating License Information using Maven2

ClearPass uses the Maven License Plugin to manage the licenses on its files. The license header is stored in the PROJECT_HOME/src/etc/header.txt file.

To update the license, first change the header.txt file then execute the following command from within PROJECT_HOME:

This will update licenses if the header.txt file has changed or if a file is missing a license. You can use this instead of remembering to add the header to each file. At some point, we may include this as part of the build process.

To check if the license has been applied, but not change any files, execute

Generating Clover Test Coverage Reports

ClearPass utilizes Clover2 from Atlassian to generate test coverage reports of its code base. These are stored in CLEARPASS_HOME/target/site/clover/ To generate the reports, use the command below:

Icon

Note, as of 1.0.0.GA, there are no tests. This will change in later versions.

Compatibility

ClearPass Version

Compatible CAS Versions

Compatible uPortal Versions

Notes

1.0.0.GA

3.3.3, 3.3.4,3.3.5

3.2-SNAPSHOT

May be compatible with other versions of CAS, but only tested on 3.3.3, 3.3.4,3.3.5.  Would work with 3.1.x version of uPortal if patch is backported.

1.0.1.GA

3.4, 3.4.1

3.2+

Updated to use 3.4.1 by default.

1.0.3.GA

3.4.2

3.2+

Updated to work Out of the Box with 3.4.2

1.0.4.GA

3.4.2

3.2+

Upgraded to latest CAS Client. Note exclusion rule added to sample project

1.0.5.GA

3.4.2

3.2+

Minor bug fix. Note exclusion rule from 1.0.4.GA release

1.0.6.GA

3.4.4

3.2+

Encrypted Password Support. Note exclusion rule from 1.0.4.GA release

1.0.7.GA

3.4.6

3.2+

Removal of username/password when ticket is expired/removed. Works with 3.4.6

1.0.8.GA3.4.11+3.2+Updated to use CAS 3.4.11 by default
3.5.03.5.x3.2+ClearPass is merged with the CAS codebase as separate extension.
4.0.03.5.x3.2+ClearPass configuration enabled encryption of credentials by default.

Download

Binary Distributions

CAS v3.5

Binary distributions are always available from the Maven Central Repository.

Prior to CAS v3.5

Binary distributions are always available from the Maven Central Repository.

Maven Dependency

Dependency Declaration

CAS v3.5

The clearpass-webapp module is merged with the cas-server-webapp module. You will however need to declare the following library dependency inside the project pom overlay:

ClearPass in CAS v3.5

The <version>...</version> should contain the version string for the version of ClearPass you are working with. (i.e. 3.5.0-RC2)

If you're getting ehcache errors add this dependency (3.5.1):

ClearPass in CAS v3.5

 

Prior to CAS v3.5

  • Web App Module

To declare the web application as a dependency, add the following snippet of XML to your project's pom.xml:

CAS v3.5

The <version>...</version> should contain the version string for the version of ClearPass you are working with. 

  • Library Only

While most people will want to bring in the web application module as a dependency, those who wish can instead bring in the core code, and re-create the required configuration in their own web application module. To do this, you would need to have the following dependency:

clearpass-impl library

The <version>...</version> should contain the version string for the version of ClearPass you are working with.

Installation Instructions

Icon

Please note, these instructions assume you're performing a Maven2 WAR Overlay and thus, incorporating the clearpass-webapp or the cas-server-webapp module and not the clearpass- library module. Those who are not using the Maven2 WAR Overlay method would need to copy all of the files in the clearpass-webapp module into their own CAS Web Application.

CAS v3.5

ClearPass by default is turned off in CAS v3.5. In order to enable the functionality, follow the below steps in your overlay:

Step 0 Acquiring the Dependency

We're assuming you've already done the work to include the cas-server-extension-clearpass module as specified above!

Step 1: Modifying deployerConfigContext.xml

Uncomment the below element that is responsible for capturing and caching the password:

AuthenticationMetaDataPopulator

Step 2: Modifying web.xml

For the CAS version that you're going to be using, obtain its web.xml (either from SVN, or from the binary download). Place that in your project's WEB-INF directory and open it in your favorite text editor!

Add the following servlet-mapping into your web.xml:

clearpass servlet mapping

This enables ClearPass in the default location. Be sure to put this snippet with the other servlet-mappings!

Next, add the following filter and filter-mapping into your web.xml:

clearpass spring security filters

Be sure to put this snippet with the other filter and filter-mappings!

Step 3: Modifying clearpass-configuration.xml 

For the CAS version that you're going to be using, obtain a copy of the clearpass-configuration.xml file inside the WEB-INF/unused-spring-configuration of the project. Place that in your project's WEB-INF/spring-configuration directory and open it in your favorite text editor!

Add the spring util namespace and schema location to the beans definition:

Spring util namespace

Relevant entries added are "xmlns:util" and the "spring-util.3.1.xsd" schema location.

Declare the following bean inside the file:

list of clearpass proxying service

The above bean defines the list of proxying services authorized to obtain clearpass credentials.

Alternatively, you may replace:

with:

...to allow all proxying services to be able to obtain clearpass credentials.

 

Don't allow all services to access ClearPass in production

Icon

It's probably not appropriate in your environment to allow any service that can obtain a proxy ticket to proxy to ClearPass. Explicitly authorizing proxy chains to access ClearPass (and denying all unauthorized proxy chains) is an important access control on release of the end-user's password.

 

Step 4: Modifying ticketRegistry.xml

For the CAS version that you're going to be using, obtain a copy of the ticketRegistry.xml file inside the WEB-INF/spring-configuration of the project. Place that in your project's WEB-INF/spring-configuration directory and open it in your favorite text editor!

Replace:

Ticket Registry

with:

Ticket Registry

Step 5: Modifying cas.properties

For the CAS version that you're going to be using, obtain a copy of the cas.properties file inside the WEB-INF of the project. Place that in your project's WEB-INF directory

Set an appropriate value for the server.name property:

server name property

Step 6: Build Your CAS Deployment

Build your CAS deployment as you normally would.

 


Prior to CAS v3.5

These instructions as source code

Icon

There's a repository on github that includes the Maven configuration to perform this Maven overlay approach.

http://github.com/wgthom/clearpass-cas

With the 1.0.0.GA release, every attempt has been made to ensure that the minimal number of steps must be completed to enable ClearPass.

Step 0 Acquiring the Dependency

We're assuming you've already done the work to include the clearpass-webapp module as specified above!

Step 1: Modifying deployerConfigContext.xml

We're going to add an AuthenticationMetaDataPopulator to the CAS AuthenticationManager to capture the password and cache it:

Open up your CAS deployment's deployerConfigContext.xml in your favorite XML or text editor. Find your AuthenticationManager and add the following between the <bean id="authenticationManager">...</bean>:

Save and close your deployerConfigContext.xml

Step 2: Modifying web.xml

For the CAS version that you're going to be using, obtain its web.xml (either from SVN, or from the binary download). Place that in your project's WEB-INF directory and open it in your favorite text editor!

Add the following into your web.xml:

This enables ClearPass in the default location. Be sure to put this snippet with the other servlet-mappings! Next, you'll want to configure the security for your ClearPass Service. By default, we recommend using CAS Proxy tickets, and that is shown below (using the Jasig CAS Client). You could in theory replace this with another mechanism such as Service Accounts with BASIC Auth etc.

See Configuring the Jasig CAS Client for Java in the web.xml for more information on configuration options for the CAS Client. More advanced users may wish to take advantage of the Spring configuration or JNDI configuration. Be sure to replace the set of allowedProxyChains with your own list of chains authorized to receive proxy tickets.

Icon

The above configuration will result in a 403 response being returned if there is an exception validating the ticket.

Step 3: Build Your CAS Deployment

Build your CAS deployment as you normally would.

Example Maven2 WAR Overlay Project

We've constructed a sample WAR Maven2 project that already incorporates the steps listed above. You would just need to add your local configuration to this sample (i.e. modified deployerConfigContext.xml).