Java Apereo CAS Client

Intro

This is the official home of the Java Apereo CAS client. The client consists of a collection of Servlet filters that are suitable for most Java-based web applications. It also serves as an API platform to interact with the CAS server programmatically to make authentication requests, validate tickets and consume principal attributes.

All client artifacts are published to Maven central. Depending on functionality, applications will need include one or more of the listed dependencies in their configuration.

Build

git clone git@github.com:apereo/java-cas-client.git
cd java-cas-client
mvn clean package

Components

• Core functionality, which includes CAS authentication/validation filters.

<dependency>
    <groupId>org.apereo.cas.client</groupId>
    <artifactId>cas-client-core</artifactId>
    <version>${java.cas.client.version}</version>
</dependency>

• Support for SAML functionality is provided by this dependency:

<dependency>
   <groupId>org.apereo.cas.client</groupId>
   <artifactId>cas-client-support-saml</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Distributed proxy ticket caching with Ehcache is provided by this dependency:

<dependency>
   <groupId>org.apereo.cas.client</groupId>
   <artifactId>cas-client-support-distributed-ehcache</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Distributed proxy ticket caching with Memcached is provided by this dependency:

<dependency>
   <groupId>org.apereo.cas.client</groupId>
   <artifactId>cas-client-support-distributed-memcached</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Spring Boot AutoConfiguration is provided by this dependency:

<dependency>
   <groupId>org.apereo.cas.client</groupId>
   <artifactId>cas-client-support-springboot</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

Configuration

Strategies

The client provides multiple strategies for the deployer to provide client settings. The following strategies are supported:

• JNDI (JNDI)
• Properties File (PROPERTY_FILE). The configuration is provided via an external properties file. The path may be specified in the web context as such:

<context-param>
    <param-name>configFileLocation</param-name>
    <param-value>/etc/cas/file.properties</param-value>
</context-param>

If no location is specified, by default /etc/java-cas-client.properties will be used.

• System Properties (SYSTEM_PROPERTIES)
• Web Context (WEB_XML)
• Default (DEFAULT)

In order to instruct the client to pick a strategy, strategy name must be specified in the web application's context:

<context-param>
    <param-name>configurationStrategy</param-name>
    <param-value>DEFAULT</param-value>
</context-param>

If no configurationStrategy is defined, DEFAULT is used which is a combination of WEB_XML and JNDI.

Client Configuration Using web.xml

The client can be configured in web.xml via a series of context-params and filter init-params. Each filter for the client has a required (and optional) set of properties. The filters are designed to look for these properties in the following way:

• Check the filter's local init-params for a parameter matching the required property name.
• Check the context-params for a parameter matching the required property name.
• If two properties are found with the same name in the init-params and the context-params, the init-param takes precedence.

Note: If you're using the serverName property, you should note well that the fragment-URI (the stuff after the #) is not sent to the server by all browsers, thus the CAS client can't capture it as part of the URL.

An example application that is protected by the client is available here.

org.apereo.cas.client.authentication.AuthenticationFilter

The AuthenticationFilter is what detects whether a user needs to be authenticated or not. If a user needs to be authenticated, it will redirect the user to the CAS server.

<filter>
  <filter-name>CAS Authentication Filter</filter-name>
  <filter-class>org.apereo.cas.client.authentication.AuthenticationFilter</filter-class>
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>https://battags.ad.ess.rutgers.edu:8443/cas</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>http://www.acme-client.com</param-value>
  </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Authentication Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

Ignore Patterns

The following types are supported:

org.apereo.cas.client.authentication.Saml11AuthenticationFilter

The SAML 1.1 AuthenticationFilter is what detects whether a user needs to be authenticated or not. If a user needs to be authenticated, it will redirect the user to the CAS server.

<filter>
  <filter-name>CAS Authentication Filter</filter-name>
  <filter-class>org.apereo.cas.client.authentication.Saml11AuthenticationFilter</filter-class>
  <init-param>
    <param-name>casServerLoginUrl</param-name>
    <param-value>https://somewhere.cas.edu:8443/cas/login</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>http://www.the-client.com</param-value>
  </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Authentication Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>