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

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:

https://github.com/Jasig/cas/tree/master/cas-server-extension-clearpass

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

https://github.com/Unicon/clearpass

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:

git clone https://github.com/Jasig/cas.git

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

git clone https://github.com/Unicon/clearpass.git

Issue Tracker

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

http://issues.jasig.org/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

Compatibility

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:

<dependency>
   <groupId>org.jasig.cas</groupId>
   <artifactId>cas-server-extension-clearpass</artifactId>
   <version>${cas.clearpass.version}</version>
   <scope>runtime</scope>
</dependency>

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

<dependency>
     <groupId>net.sf.ehcache</groupId>
     <artifactId>ehcache-core</artifactId>
     <version>2.2.0</version>
</dependency>

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:

<dependency>
   <groupId>org.jasig.cas3.extensions</groupId>
   <artifactId>clearpass-webapp</artifactId>
   <version>${cas.clearpass.version}</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. 

• 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>${cas.clearpass.version}</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

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:

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

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:

<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 snippet with the other servlet-mappings!

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

<filter>
  <filter-name>clearPassFilterChainProxy</filter-name>
  <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
</filter>

<filter-mapping>
  <filter-name>clearPassFilterChainProxy</filter-name>
  <url-pattern>/clearPass</url-pattern>
</filter-mapping>

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:

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:sec="http://www.springframework.org/schema/security"
       xmlns:util="http://www.springframework.org/schema/util"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
       http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-3.1.xsd
       http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.1.xsd">
...

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

Declare the following bean inside the file:

<bean id="clearPassProxyList" class="org.jasig.cas.client.validation.ProxyList">
    <constructor-arg>
        <list>
            <value>https://proxy.server.edu/proxyCallback</value>
            <value>...</value>
        </list>
    </constructor-arg>
</bean>

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

Alternatively, you may replace:

<property name="allowedProxyChains" ref="clearPassProxyList" />

with:

<property name="acceptAnyProxy" value="true" />

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

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:

<bean id="ticketRegistry" class="org.jasig.cas.ticket.registry.DefaultTicketRegistry" />

with:

<bean id="ticketRegistryValue" class="org.jasig.cas.ticket.registry.DefaultTicketRegistry" />

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=https://cas.server.edu

Step 6: Build Your CAS Deployment

Build your CAS deployment as you normally would.

Prior to CAS v3.5

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

<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/uPortal/CasProxyServlet</param-value>
  </init-param>
  <init-param>
     <param-name>useSession</param-name>
     <param-value>false</param-value>
  </init-param>
  <init-param>
     <param-name>redirectAfterValidation</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 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.

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