ClearPass

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
   

   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:

   <cas:clearPassResponse xmlns:cas='http://www.yale.edu/tp/cas'>
   	<cas:clearPassSuccess>
   		<cas:credentials>actual_password</cas:credentials>
   	</cas:clearPassSuccess>
   </cas:clearPassResponse>

   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:

   <cas:clearPassResponse xmlns:cas='http://www.yale.edu/tp/cas'>
   	<cas:clearPassFailure>description of the problem</cas:clearPassFailure>
   </cas:clearPassResponse>

Source Control

Source Code Location

The source code for the ClearPass Extension is currently located on the JASIG SVN Server. The JASIG SVN Server is located at:

https://www.ja-sig.org/svn

Accessing the Source

Web

To view the source via the web please visit the following url:

https://www.ja-sig.org/svn/cas-extensions/clearpass/trunk

Command Line

svn co https://www.ja-sig.org/svn/cas-extensions/clearpass/trunk

Issue Tracker

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

http://www.ja-sig.org/issues/browse/CPE

Building

Building ClearPass using Maven2

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

mvn clean package install

• "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:

mvn license:format

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

mvn license:check

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:

mvn clover2:instrument clover2:aggregate clover2:clover

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

Compatibility

Download

Binary Distributions

Binary distributions are always available from the Jasig Download Center

Maven2 Dependency

Maven2 Repository

Currently, ClearPass is only available from the Jasig Maven2 Repository:

<repository>
   <id>ja-sig</id>
   <url>http://oss.sonatype.org/content/repositories/releases/</url>
</repository>

This should be placed in your project's pom.xml within a <repositories>...</repositories> block.

Dependency Declaration

Web App Module

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

<dependency>
   <groupId>org.jasig.cas3.extensions</groupId>
   <artifactId>clearpass-webapp</artifactId>
   <version>1.0.1.GA</version>
   <scope>runtime</scope>
   <type>war</type>
</dependency>

The <version>...</version> should contain the version string for the version of ClearPass you are working with. If you're working with the web application, you can follow the installation instructions below. You must remember to include the CAS web application as a dependency also.

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:

<dependency>
   <groupId>org.jasig.cas3.extensions</groupId>
   <artifactId>clearpass-impl</artifactId>
   <version>1.0.1.GA</version>
   <scope>runtime</scope>
   <type>jar</type>
</dependency>

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

Installation Instructions

Please note, these instructions assume you're performing a Maven2 WAR Overlay, and thus, incorporating the clearpass-webapp module and not the clearpass-impl 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.

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:

<bean class="org.jasig.cas3.extensions.clearpass.CacheCredentialsMetaDataPopulator">
   <constructor-arg index="0" ref="credentialsCache" />
</bean>

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

<property name="authenticationMetaDataPopulators">
   <list>
      <bean class="org.jasig.cas3.extensions.clearpass.CacheCredentialsMetaDataPopulator">
         <constructor-arg index="0" ref="credentialsCache" />
      </bean>
   </list>
</property>

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:

<servlet-mapping>
	<servlet-name>cas</servlet-name>
	<url-pattern>/clearPass</url-pattern>
</servlet-mapping>

This enables ClearPass in the default location. Be sure to put this snippit 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.

<filter>
  <filter-name>CAS Validation Filter</filter-name>
  <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class>
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>https://my.cas.server.com/cas</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>https://my.clearpass.cas.instance/</param-value>
  </init-param>
  <init-param>
     <param-name>exceptionOnValidationFailure</param-name>
     <param-value>false</param-value>
  </init-param>
  <init-param>
     <param-name>allowedProxyChains</param-name>
     <param-value>http://my.uportal.edu/CasProxyServlet</param-value>
  </init-param>
  <init-param>
     <param-name>useSession</param-name>
     <param-value>false</param-value>
  </init-param>
</filter>

<filter>
  <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
  <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class>
</filter>

<filter-mapping>
	<filter-name>CAS Validation Filter</filter-name>
	<url-pattern>/clearPass</url-pattern>
</filter-mapping>

<filter-mapping>
	<filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
	<url-pattern>/clearPass</url-pattern>
</filter-mapping>

See Configuring the JA-SIG 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.

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).

• Example Local CAS Deployment