CAS官方文档

Build
git clone git@:Jasig/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</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</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</groupId>
<artifactId>cas-client-support-distributed-memcached</artifactId>
<version>${java.cas.client.version}</version>
</dependency>
∙Atlassian integration is provided by this dependency:
<dependency>
<groupId>org.jasig.cas</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</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</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</groupId>
<artifactId>cas-client-integration-tomcat-v7</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:
<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-param s and filter init-param s. 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-param s for a parameter matching the required property name.
∙Check the context-param s for a parameter matching the required property name.
∙If two properties are found with the same name in the init-param s and the context-param s, 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-clas s>
<init-param>
<param-name>casServerLoginUrl</param-name>
<param-value>https://:8443/cas/login</param-value>
</init-param>
<param-name>serverName</param-name>
<param-value></param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CAS Authentication Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Property Description Required
casServerLoginUrl Defines the location of the CAS server
login URL,
i.e. https://localhost:8443/cas/login
Yes
serverName The name of the server this application is hosted on. Service URL will be dynamically constructed using this, i.e.
https://localhost:8443 (you must include
the protocol, but port is optional if it's
a standard port).
Yes
service The service URL to send to the CAS server,
i.e.https://localhost:8443/yourwebapp/index.html
No
renew specifies whether renew=true should be
sent to the CAS server. Valid values are either true/false(or no value at all). Note
that renew cannot be specified as
local init-param setting.
No
gateway specifies whether gateway=true should be
sent to the CAS server. Valid values are either true/false(or no value at all)
No
artifactParameterName specifies the name of the request parameter
on where to find the artifact
(i.e. ticket).
No
serviceParameterName specifies the name of the request parameter
on where to find the service (i.e. service)
No
encodeServiceUrl Whether the client should auto encode the service url. Defaults to true
No
ignorePattern Defines the url pattern to ignore, when intercepting authentication requests.
No
Property Description Required
ignoreUrlPatternType Defines the type of the pattern specified. Defaults to REGEX. Other types
are CONTAINS,EXACT.
No
gatewayStorageClass The storage class used to record gateway requests
No
authenticationRedirectStrategyClass The class name of the component to decide
how to handle authn redirects to CAS
No
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</filte
r-class>
<init-param>
<param-name>casServerLoginUrl</param-name>
<param-value>https://:8443/cas/login</param-value>
</init-param>
<init-param>
<param-name>serverName</param-name>
<param-value></param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CAS Authentication Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Property Description Required
casServerLoginUrl Defines the location of the CAS server login URL,
i.e.https://localhost:8443/cas/login
Yes
serverName The name of the server this application is hosted
on. Service URL will be dynamically constructed
using this, i.e. https://localhost:8443 (you must include the protocol, but port is optional if it's
a standard port).
Yes
Property Description Required
service The service URL to send to the CAS server,
i.e.https://localhost:8443/yourwebapp/index.html
No
renew specifies whether renew=true should be sent to the
CAS server. Valid values are either true/false(or
no value at all). Note that renew cannot be
specified as local init-param setting.
No
gateway specifies whether gateway=true should be sent to
the CAS server. Valid values are
either true/false(or no value at all)
No
artifactParameterName specifies the name of the request parameter on where
to find the artifact (i.e. SAMLart).
No
serviceParameterName specifies the name of the request parameter on where
to find the service (i.e. TARGET)
No
encodeServiceUrl Whether the client should auto encode the service
url. Defaults to true
No
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-c
lass>
<init-param>
<param-name>casServerUrlPrefix</param-name>
<param-value>https://:8443/cas</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CAS Validation Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Property Description
casServerUrlPrefix The start of the CAS server URL, i.e.https://localhost:8443/cas serverName The name of the server this application is hosted on. Service
Property Description
will be dynamically constructed using this,
i.e. https://localhost:8443(you must include the protocol, b
port is optional if it's a standard port).
renew Specifies whether renew=true should be sent to the CAS ser Valid values are either true/false(or no value at all). Not that renew cannot be specified as local init-param setting.
redirectAfterValidation Whether to redirect to the same URL after ticket validation, without the ticket in the parameter. Defaults to true.
useSession Whether to store the Assertion in session or not. If sessions not used, tickets will be required for each request. Defaul to true.
exceptionOnValidationFailure Whether to throw an exception or not on ticket validation fail Defaults to true.
sslConfigFile A reference to a properties file that includes SSL settings client-side SSL config, used during back-channel calls. The configuration includes keys for protocol which defaults
to SSL,keyStoreType, keyStorePath, keyStorePass,keyManagerType w defaults to SunX509and certificatePassword.
encoding Specifies the encoding charset the client should use hostnameVerifier Hostname verifier class name, used when making back-channel c 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://:8443/cas</param-value>
</init-param>
<init-param>
<param-name>serverName</param-name>
<param-value></param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CAS Validation Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Property Description casServerUrlPrefix The start of the CAS server URL, i.e.https://localhost:8443/cas
serverName The name of the server this application is hosted on. Service will be dynamically constructed using this,
i.e. https://localhost:8443(you must include the protocol, b port is optional if it's a standard port).
renew Specifies whether renew=true should be sent to the CAS ser Valid values are either true/false(or no value at all). Not that renew cannot be specified as local init-param setting.
redirectAfterValidation Whether to redirect to the same URL after ticket validation, without the ticket in the parameter. Defaults to true.
useSession Whether to store the Assertion in session or not. If sessions not used, tickets will be required for each request. Defaul to true.
exceptionOnValidationFailure whether to throw an exception or not on ticket validation fail Defaults to true
tolerance The tolerance for drifting clocks when validating SAML tick Note that 10 seconds should be more than enough for most environments that have NTP time synchronization. Defaults to msec
sslConfigFile A reference to a properties file that includes SSL settings client-side SSL config, used during back-channel calls. The configuration includes keys for protocol which defaults
to SSL,keyStoreType, keyStorePath, keyStorePass,keyManagerType w defaults to SunX509and certificatePassword.
encoding Specifies the encoding charset the client should use hostnameVerifier Hostname verifier class name, used when making back-channel c 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.Cas20ProxyReceivingTicketValidationFi
lter</filter-class>
<init-param>
<param-name>casServerUrlPrefix</param-name>
<param-value>https://:8443/cas</param-value>
</init-param>
<init-param>
<param-name>serverName</param-name>
<param-value></param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CAS Validation Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Property Description casServerUrlPrefix The start of the CAS server URL, i.e.https://localhost:8443/
serverName The name of the server this application is hosted on. Serv will be dynamically constructed using this,
i.e.https://localhost:8443(you must include the protocol, b is optional if it's a standard port).
renew Specifies whether renew=true should be sent to the CAS s Valid values are either true/false(or no value at all). N that renew cannot be specified as local init-param settin
redirectAfterValidation Whether to redirect to the same URL after ticket validati without the ticket in the parameter. Defaults to true.
useSession Whether to store the Assertion in session or not. If sessi not used, tickets will be required for each request. Def to true.
exceptionOnValidationFailure whether to throw an exception or not on ticket validation f Defaults to true
proxyReceptorUrl The URL to watch for PGTIOU/PGT responses from the CAS s Should be defined from the root of the context. For exam your application is deployed in /cas-client-app and you wan
Property Description
proxy receptor URL to be/cas-client-app/my/receptor you need
configure proxyReceptorUrl to be/my/receptor. acceptAnyProxy Specifies whether any proxy is OK. Defaults to false.
allowedProxyChains Specifies the proxy chain. Each acceptable proxy chain s include a space-separated list of URLs. Each acceptable prox should appear on its own line.
proxyCallbackUrl The callback URL to provide the CAS server to accept Proxy G Tickets.
proxyGrantingTicketStorageClass Specify an implementation of the ProxyGrantingTicketStorag that has a no-arg constructor.
sslConfigFile A reference to a properties file that includes SSL setti client-side SSL config, used during back-channel calls. configuration includes keys for protocol which defaults to SSL, keyStoreType, keyStorePath,keyStorePass, keyManagerType defaults to SunX509and certificatePassword.
encoding Specifies the encoding charset the client should use
secretKey The secret key used by the proxyGrantingTicketStorageClass if supports encryption.
cipherAlgorithm The algorithm used by the proxyGrantingTicketStorageClass if i supports encryption. Defaults to DESede
millisBetweenCleanUps Startup delay for the cleanup task to remove expired ticke the storage. Defaults to60000 msec
ticketValidatorClass Ticket validator class to use/create
hostnameVerifier Hostname verifier class name, used when making back-channe 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.
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 separate lines. BE SURE NOT TO HAVE EXTRA LINE BREAKS.
org.jasig.cas.client.util.HttpServletRequestWrapperFilter
Wraps an HttpServletRequest so that the getRemoteUser and getPrincipal return the CAS related entries.
org.jasig.cas.client.util.AssertionThreadLocalFilter
Places the Assertion in a ThreadLocal for portions of the application that need access to it. This is useful when the Web application that this filter "fronts" needs to get the Principal name, but it has no access to the HttpServletRequest, hence making getRemoteUser() call impossible.
<filter>
<filter-name>CAS Assertion Thread Local Filter</filter-name>
<filter-class>org.jasig.cas.client.util.AssertionThreadLocalFilter</filter-class> </filter>
<filter-mapping>
<filter-name>CAS Assertion Thread Local Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Client Configuration Using Spring
Configuration via Spring IoC will depend heavily on DelegatingFilterProxy class. For each filter that will be configured for CAS via Spring, a corresponding DelegatingFilterProxy is needed in the web.xml.
As
the SingleSignOutFilter, HttpServletRequestWrapperFilter and AssertionThreadLocalFilte r have no configuration options, we recommend you just configure them in the web.xml
<filter>
<filter-name>CAS Authentication Filter</filter-name>
<filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> <init-param>
<param-name>targetBeanName</param-name>
<param-value>authenticationFilter</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CAS Authentication Filter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Bean Configuration
AuthenticationFilter
<bean
name="authenticationFilter"
class="org.jasig.cas.client.authentication.AuthenticationFilter"
p:casServerLoginUrl="https://localhost:8443/cas/login"
p:renew="false"
p:gateway="false"
p:service="https:///cas-client" />
Cas10TicketValidationFilter
<bean
name="ticketValidationFilter"
class="org.jasig.cas.client.validation.Cas10TicketValidationFilter"
p:service="https:///cas-client">
<property name="ticketValidator">
<bean class="org.jasig.cas.client.validation.Cas10TicketValidator">
<constructor-arg index="0"value="https://localhost:8443/cas" />
</bean>
</property>
</bean>
Saml11TicketValidationFilter
<bean
name="ticketValidationFilter"
class="org.jasig.cas.client.validation.Saml11TicketValidationFilter"
p:service="https:///cas-client">
<property name="ticketValidator">
<bean class="org.jasig.cas.client.validation.Saml11TicketValidator">
<constructor-arg index="0"value="https://localhost:8443/cas" />
</bean>
</property>
</bean>
Cas20ProxyReceivingTicketValidationFilter
Configuration to validate tickets:
<bean
name="ticketValidationFilter"
class="org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter"
p:service="https:///cas-client">
<property name="ticketValidator">
<bean class="org.jasig.cas.client.validation.Cas20ServiceTicketValidator"> <constructor-arg index="0"value="https://localhost:8443/cas" />
</bean>
</property>
</bean>
Configuration to accept a Proxy Granting Ticket:
<bean
name="ticketValidationFilter"
class="org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter"
p:service="https:///cas-client"
p:proxyReceptorUrl="/proxy/receptor">
<property name="ticketValidator">
<bean
class="org.jasig.cas.client.validation.Cas20ServiceTicketValidator"
p:proxyCallbackUrl="/proxy/receptor">
<constructor-arg index="0"value="https://localhost:8443/cas" />
</bean>
</property>
</bean>
Configuration to accept any Proxy Ticket (and Proxy Granting Tickets):
<bean
name="ticketValidationFilter"
class="org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter"
p:service="https:///cas-client"
p:proxyReceptorUrl="/proxy/receptor">
<property name="ticketValidator">
<bean class="org.jasig.cas.client.validation.Cas20ProxyTicketValidator"
p:acceptAnyProxy="true"
p:proxyCallbackUrl="/proxy/receptor">
<constructor-arg index="0"value="https://localhost:8443/cas" />
</bean>
</property>
</bean>
Configuration to accept Proxy Ticket from a chain (and Proxy Granting Tickets):
<bean
name="ticketValidationFilter"
class="org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter"
p:service="https:///cas-client"
p:proxyReceptorUrl="/proxy/receptor">
<property name="ticketValidator">
<bean class="org.jasig.cas.client.validation.Cas20ProxyTicketValidator"
p:proxyCallbackUrl="/proxy/receptor">
<constructor-arg index="0"value="https://localhost:8443/cas" />
<property name="allowedProxyChains">
<list>
<value>http://proxy1 http://proxy2</value>
</list>
</property>
</bean>
</property>
</bean>
The specific filters can be configured in the following ways. Please see the JavaDocs included in the distribution for specific required and optional properties:
Client Configuration Using JNDI
Configuring the CAS client via JNDI is essentially the same as configuring the client via the web.xml, except the properties will reside in JNDI and not in the web.xml. All properties that are placed in JNDI should be placed under java:comp/env/cas
We use the following conventions: 1. JNDI will first look in java:comp/env/cas/{SHORT FILTER NAME}/{PROPERTY NAME} (i.e. java:comp/env/cas/AuthenticationFilter/serverName) 2. JNDI will as a last resort look in java:comp/env/cas/{PROPERTY NAME} (i.e. java:comp/env/cas/serverName)
This is an update to the META-INF/context.xml that is included in Tomcat's Manager application:
<?xml version="1.0" encoding="UTF-8"?>
<Context antiResourceLocking="false"privileged="true">
<Environment description="Server Name"name="cas/serverName"override="false"
type="ng.String"value="http://localhost:8080"/>
<Environment description="CAS Login Url"
name="cas/AuthenticationFilter/casServerLoginUrl"override="false"
type="ng.String"value="https:///cas/login"/>
<Environment description="CAS Url Prefix"
name="cas/Cas20ProxyReceivingTicketValidationFilter/casServerUrlPrefix"
override="false"
type="ng.String"value="https:///cas"/>
</Context>
Configuring Single Sign Out
The Single Sign Out support in CAS consists of configuring one SingleSignOutFilter and
one ContextListener. Please note that if you have configured the CAS Client for Java as Web filters,
this filter must come before the other filters as described.
The SingleSignOutFilter can affect character encoding. This becomes most obvious when used in
conjunction with applications such as Atlassian Confluence. Its recommended you explicitly configure
either the VT Character Encoding Filter or the Spring Character Encoding Filter with explicit encodings.
Configuration
Property Description Required
artifactParameterName The ticket artifact parameter name. Defaults
to ticket
No
logoutParameterName Defaults to logoutRequest No frontLogoutParameterName Defaults to SAMLRequest No relayStateParameterName Defaults to RelayState No eagerlyCreateSessions Defaults to true No artifactParameterOverPost Defaults to false No casServerUrlPrefix URL to root of CAS Web application context. Yes CAS Protocol。