开源软件名称：

开源软件地址：

开源编程语言：

开源软件介绍：

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 [email protected]:apereo/java-cas-client.git
cd java-cas-client
mvn clean package

Please note that to be deployed in Maven Central, we mark a number of JARs as provided (related to JBoss and Memcache Clients). In order to build the clients, you must enable the commented out repositories in the appropriate pom.xml files in the modules (cas-client-integration-jboss and cas-client-support-distributed-memcached) or follow the instructions on how to install the file manually.

Components

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

<dependency>
    <groupId>org.jasig.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.jasig.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.jasig.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.jasig.cas.client</groupId>
   <artifactId>cas-client-support-distributed-memcached</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Atlassian integration (Deprecated) is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-atlassian</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• JBoss integration is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-jboss</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Tomcat 6 integration is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-tomcat-v6</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Tomcat 7 is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-tomcat-v7</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Tomcat 8.0.x is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-tomcat-v8</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Tomcat 8.5.x is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-tomcat-v85</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Tomcat 9.0.x is provided by this dependency:

<dependency>
   <groupId>org.jasig.cas.client</groupId>
   <artifactId>cas-client-integration-tomcat-v90</artifactId>
   <version>${java.cas.client.version}</version>
</dependency>

• Spring Boot AutoConfiguration is provided by this dependency:

<dependency>
   <groupId>org.jasig.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.jasig.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.jasig.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.jasig.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.jasig.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>

org.jasig.cas.client.validation.Cas10TicketValidationFilter

Validates tickets using the CAS 1.0 Protocol.

<filter>
  <filter-name>CAS Validation Filter</filter-name>
  <filter-class>org.jasig.cas.client.validation.Cas10TicketValidationFilter</filter-class>
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>https://somewhere.cas.edu:8443/cas</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 Validation Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

org.jasig.cas.client.validation.Saml11TicketValidationFilter

Validates tickets using the SAML 1.1 protocol.

<filter>
  <filter-name>CAS Validation Filter</filter-name>
  <filter-class>org.jasig.cas.client.validation.Saml11TicketValidationFilter</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 Validation Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter

Validates the tickets using the CAS 2.0 protocol. If you provide either the acceptAnyProxy or the allowedProxyChains parameters, a Cas20ProxyTicketValidator will be constructed. Otherwise a general Cas20ServiceTicketValidator will be constructed that does not accept proxy tickets.

Note: If you are using proxy validation, you should place the filter-mapping of the validation filter before the authentication filter.

<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://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 Validation Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

org.jasig.cas.client.validation.Cas30ProxyReceivingTicketValidationFilter

Validates the tickets using the CAS 3.0 protocol. If you provide either the acceptAnyProxy or the allowedProxyChains parameters, a Cas30ProxyTicketValidator will be constructed. Otherwise a general Cas30ServiceTicketValidator will be constructed that does not accept proxy tickets. Supports all configurations that are available for Cas20ProxyReceivingTicketValidationFilter.

org.jasig.cas.client.validation.json.Cas30JsonProxyReceivingTicketValidationFilter

Indentical to Cas30ProxyReceivingTicketValidationFilter, yet the filter is able to accept validation responses from CAS that are formatted as JSON per guidelines laid out by the CAS protocol. See the protocol documentation for more info.

Proxy Authentication vs. Distributed Caching

The client has support for clustering and distributing the TGT state among application nodes that are behind a load balancer. In order to do so, the parameter needs to be defined as such for the filter.

Ehcache

Configure the client:

<init-param>
  <param-name>proxyGrantingTicketStorageClass</param-name>
  <param-value>org.jasig.cas.client.proxy.EhcacheBackedProxyGrantingTicketStorageImpl</param-value>
</init-param>

The setting provides an implementation for proxy storage using EhCache to take advantage of its replication features so that the PGT is successfully replicated and shared among nodes, regardless which node is selected as the result of the load balancer rerouting.

Configuration of this parameter is not enough. The EhCache configuration needs to enable the replication mechanism through once of its suggested ways. A sample of that configuration based on RMI replication can be found here. Please note that while the sample is done for a distributed ticket registry implementation, the basic idea and configuration should easily be transferable.

When loading from the web.xml, the Jasig CAS Client relies on a series of default values, one of which being that the cache must be configured in the default location (i.e. classpath:ehcache.xml).

<cacheManagerPeerProviderFactory class="net.sf.ehcache.distribution.RMICacheManagerPeerProviderFactory"
   properties="peerDiscovery=automatic,
   multicastGroupAddress=230.0.0.1, multicastGroupPort=4446"/>
 
<cacheManagerPeerListenerFactory class="net.sf.ehcache.distribution.RMICacheManagerPeerListenerFactory"/>
 
<cache
   name="org.jasig.cas.client.proxy.EhcacheBackedProxyGrantingTicketStorageImpl.cache"
   maxElementsInMemory="100"
   eternal="false"
   timeToIdleSeconds="100"
   timeToLiveSeconds="100"
   overflowToDisk="false">
   <cacheEventListenerFactory class="net.sf.ehcache.distribution.RMICacheReplicatorFactory"/>
</cache>

Memcached

A similar implementation based on Memcached is also available.

Configure the client:

<init-param>
  <param-name>proxyGrantingTicketStorageClass</param-name>
  <param-value>org.jasig.cas.client.proxy. MemcachedBackedProxyGrantingTicketStorageImpl</param-value>
</init-param>

When loading from the web.xml, the Client relies on a series of default values, one of which being that the list of memcached servers must be defined in /cas/casclient_memcached_hosts.txt on the classpath). The file is a simple list of <hostname>:<ports> on separat