Configuring the JA-SIG CAS Client for Java in the web.xml

The CAS Client for Java 3.1 can be configured via web.xml via a series of context-params and filter init-params. Each filter for the CAS 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's parameters for a parameter matching the required property name. If two properties are found with the same name in the init-params and the context's params, the init-param takes precedence. This method of configuration is useful in the scenario where two filters share properties (such as the renew property). Note: The correct order of the filters in web.xml is necessary: AuthenticationFilter TicketValidationFilter (whichever one is chosen) HttpServletRequestWrapperFilter AssertionThreadLocalFilter Available filters are as follows: 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>casServerLoginUrl</param-name> <param-value>https://battags.ad.ess.rutgers.edu:8443/cas/login</param-value> </init-param> </filter> Required Properties casServerLoginUrl - Defines the location of the CAS server login URL, i.e. https://localhost:8443/cas/login service - the service URL to send to the CAS server, e.g. https://localhost:8443/yourwebapp/index.html serverName - the server 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). Optional Properties renew - specifies whether renew=true should be sent to the CAS server. Valid values are either "true" or "false" (or no value at all). gateway - specifies whether gateway=true should be sent to the CAS server. Valid values are either "true" or "false" (or no value at all). artifactParameterName - specifies the name of the request parameter on where to find the artifact (i.e. "ticket"). serviceParameterName - specifies the name of the request parameter on where to find the service (i.e. "service"). 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://battags.ad.ess.rutgers.edu:8443/cas</param-value> </init-param> </filter> Required Properties casServerUrlPrefix - the start of the CAS server URL, i.e. https://localhost:8443/cas. serverName - the server 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). Optional Properties redirectAfterValidation (default: true) - whether to redirect to the same URL after ticket validation, but without the ticket in the parameter. useSession (default: true) - whether to store the Assertion in session or not. If sessions are not used, tickets will be required for each request. exceptionOnValidationFailure (default: true) - whether to throw an exception or not on ticket validation failure. renew (default: false) - specifies whether renew=true should be sent to the CAS server. Valid values are either "true" or "false" 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> </filter> Required Properties casServerUrlPrefix - the start of the CAS server URL, i.e. https://localhost:8443/cas. Optional Properties redirectAfterValidation (default: true) - whether to redirect to the same URL after ticket validation, but without the ticket in the parameter. useSession (default: true) - whether to store the Assertion in session or not. If sessions are not used, tickets will be required for each request. exceptionOnValidationFailure (default: true) - whether to throw an exception or not on ticket validation failure. tolerance (default: 1000) - the tolerance for drifting clocks when validating SAML tickets. renew (default: false) - specifies whether renew=true should be sent to the CAS server. Valid values are either "true" or "false" (NOTE: Available as of version 3.1.6.) 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. If you are using proxy validation, you should map 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> Required Properties casServerUrlPrefix - the start of the CAS server URL, i.e. https://localhost:8443/cas. serverName - the start of the URL that this application is running 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). Service URL is passed to the CAS server for ticket validation. Optional Properties redirectAfterValidation (default: true) - whether to redirect to the same URL after ticket validation, but without the ticket in the parameter. useSession (default: true) - whether to store the Assertion in session or not. If sessions are not used, tickets will be required for each request. exceptionOnValidationFailure (default: true) - whether to throw an exception or not on ticket validation failure. proxyReceptorUrl (default: null) - the URL to watch for PGTIOU/PGT responses from the CAS server. Should be defined from the root of the context. For example, ff your application is deployed in /cas-client-app and you want the proxy receptor URL to be /cas-client-app/my/receptor you need to configure proxyReceptorUrl to be /my/receptor renew (default: false) - specifies whether renew=true should be sent to the CAS server. Valid values are either "true" or "false." acceptAnyProxy (default: false) - specifies whether any proxy is OK. allowedProxyChains (default: null) - specifies the proxy chain. Each acceptable proxy chain should include a space-separated list of URLs. Each acceptable proxy chain should appear on its own line. proxyCallbackUrl (default: none) - the callback URL to provide the CAS server to accept Proxy Granting Tickets. proxyGrantingTicketStorageClass (@since 3.1.9) (default: none) - specify an implementation of the ProxyGrantingTicketStorage class that has a no-arg constructor. org.jasig.cas.client.util.HttpServletRequestWrapperFilter Wraps an HttpServletRequest so that the getRemoteUser and getPrincipal return the CAS related entries. <filter> <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name> <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class> </filter> Required Properties None Optional Properties None 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>