The basic interaction between a web browser, CAS server and a Spring Security-secured service is as follows:

It's good that you're still here! Let's now look at how this is configured

This section describes how to setup Spring Security to authenticate Service Tickets. Often times this is all a web application requires. You will need to add a ServiceProperties bean to your application context. This represents your CAS service:

  <bean id="serviceProperties"
        class="org.springframework.security.cas.ServiceProperties">
    <property name="service"
        value="https://localhost:8443/cas-sample/j_spring_cas_security_check"/>
    <property name="sendRenew" value="false"/>
  </bean>
    

The service must equal a URL that will be monitored by the CasAuthenticationFilter. The sendRenew defaults to false, but should be set to true if your application is particularly sensitive. What this parameter does is tell the CAS login service that a single sign on login is unacceptable. Instead, the user will need to re-enter their username and password in order to gain access to the service.

The following beans should be configured to commence the CAS authentication process (assuming you're using a namespace configuration):

  <security:http entry-point-ref="casEntryPoint">
   ...
     <security:custom-filter position="CAS_FILTER" ref="casFilter" />
  </security:http>

  <bean id="casFilter"
        class="org.springframework.security.cas.web.CasAuthenticationFilter">
    <property name="authenticationManager" ref="authenticationManager"/>
  </bean>

  <bean id="casEntryPoint"
      class="org.springframework.security.cas.web.CasAuthenticationEntryPoint">
    <property name="loginUrl" value="https://localhost:9443/cas/login"/>
    <property name="serviceProperties" ref="serviceProperties"/>
  </bean>

    

For CAS to operate, the ExceptionTranslationFilter must have its authenticationEntryPoint property set to the CasAuthenticationEntryPoint bean. This can easily be done using entry-point-ref as is done in the example above. The CasAuthenticationEntryPoint must refer to the ServiceProperties bean (discussed above), which provides the URL to the enterprise's CAS login server. This is where the user's browser will be redirected.

The CasAuthenticationFilter has very similar properties to the UsernamePasswordAuthenticationFilter (used for form-based logins). You can use these properties to customize things like behavior for authentication success and failure.

Next you need to add a CasAuthenticationProvider and its collaborators:

  <security:authentication-manager alias="authenticationManager">
    <security:authentication-provider ref="casAuthenticationProvider" />
  </security:authentication-manager>

  <bean id="casAuthenticationProvider"
      class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
    <property name="authenticationUserDetailsService">
      <bean class="org.springframework.security.core.userdetails.UserDetailsByNameServiceWrapper">
        <constructor-arg ref="userService" />
      </bean>
    </property>
    <property name="serviceProperties" ref="serviceProperties" />
    <property name="ticketValidator">
      <bean class="org.jasig.cas.client.validation.Cas20ServiceTicketValidator">
        <constructor-arg index="0" value="https://localhost:9443/cas" />
      </bean>
    </property>
    <property name="key" value="an_id_for_this_auth_provider_only"/>
  </bean>

  <security:user-service id="userService">
    <security:user name="joe" password="joe" authorities="ROLE_USER" />
    ...
  </security:user-service>
      

The CasAuthenticationProvider uses a UserDetailsService instance to load the authorities for a user, once they have been authenticated by CAS. We've shown a simple in-memory setup here. Note that the CasAuthenticationProvider does not actually use the password for authentication, but it does use the authorities.

The beans are all reasonably self-explanatory if you refer back to the How CAS Works section.

This completes the most basic configuration for CAS. If you haven't made any mistakes, your web application should happily work within the framework of CAS single sign on. No other parts of Spring Security need to be concerned about the fact CAS handled authentication. In the following sections we will discuss some (optional) more advanced configurations.

The CAS protocol supports Single Logout and can be easily added to your Spring Security configuration. Below are updates to the Spring Security configuration that handle Single Logout

  <security:http entry-point-ref="casEntryPoint">
  ...
    <security:logout logout-success-url="/cas-logout.jsp"/>
    <security:custom-filter ref="requestSingleLogoutFilter" before="LOGOUT_FILTER"/>
    <security:custom-filter ref="singleLogoutFilter" before="CAS_FILTER"/>
  </security:http>

  <!-- This filter handles a Single Logout Request from the CAS Server -->
  <bean id="singleLogoutFilter" class="org.jasig.cas.client.session.SingleSignOutFilter"/>
  <!-- This filter redirects to the CAS Server to signal Single Logout should be performed -->
  <bean id="requestSingleLogoutFilter"
        class="org.springframework.security.web.authentication.logout.LogoutFilter">
    <constructor-arg value="https://localhost:9443/cas/logout"/>
    <constructor-arg>
      <bean class=
          "org.springframework.security.web.authentication.logout.SecurityContextLogoutHandler"/>
    </constructor-arg>
    <property name="filterProcessesUrl" value="/j_spring_cas_security_logout"/>
  </bean>
            

The logout element logs the user out of the local application, but does not terminate the session with the CAS server or any other applications that have been logged into. The requestSingleLogoutFilter filter will allow the url of /spring_security_cas_logout to be requested to redirect the application to the configured CAS Server logout url. Then the CAS Server will send a Single Logout request to all the services that were signed into. The singleLogoutFilter handles the Single Logout request by looking up the HttpSession in a static Map and then invalidating it.

It might be confusing why both the logout element and the singleLogoutFilter are needed. It is considered best practice to logout locally first since the SingleSignOutFilter just stores the HttpSession in a static Map in order to call invalidate on it. With the configuration above, the flow of logout would be:

The next step is to add the following to your web.xml

  <filter>
    <filter-name>characterEncodingFilter</filter-name>
    <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
    <init-param>
      <param-name>encoding</param-name>
      <param-value>UTF-8</param-value>
    </init-param>
  </filter>
  <filter-mapping>
    <filter-name>characterEncodingFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
  <listener>
    <listener-class>org.jasig.cas.client.session.SingleSignOutHttpSessionListener</listener-class>
  </listener>

When using the SingleSignOutFilter you might encounter some encoding issues. Therefore it is recommended to add the CharacterEncodingFilter to ensure that the character encoding is correct when using the SingleSignOutFilter. Again, refer to JASIG's documentation for details. The SingleSignOutHttpSessionListener ensures that when an HttpSession expires, the mapping used for single logout is removed.

This section describes how to authenticate to a service using CAS. In other words, this section discusses how to setup a client that uses a service that authenticates with CAS. The next section describes how to setup a stateless service to Authenticate using CAS.

  <!--
    NOTE: In a real application you should not use an in memory implementation. You will also want
          to ensure to clean up expired tickets by calling ProxyGrantingTicketStorage.cleanup()
  -->
  <bean id="pgtStorage" class="org.jasig.cas.client.proxy.ProxyGrantingTicketStorageImpl"/>

  <bean id="casAuthenticationProvider"
      class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
    ...
    <property name="ticketValidator">
      <bean class="org.jasig.cas.client.validation.Cas20ProxyTicketValidator">
        <constructor-arg value="https://localhost:9443/cas"/>

        <property name="proxyCallbackUrl"
            value="https://localhost:8443/cas-sample/j_spring_cas_security_proxyreceptor"/>
        <property name="proxyGrantingTicketStorage" ref="pgtStorage"/>
      </bean>
    </property>
  </bean>

  <bean id="casFilter"
        class="org.springframework.security.cas.web.CasAuthenticationFilter">
    ...
    <property name="proxyGrantingTicketStorage" ref="pgtStorage"/>
    <property name="proxyReceptorUrl" value="/j_spring_cas_security_proxyreceptor"/>
  </bean>

  protected void doGet(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException {
    // NOTE: The CasAuthenticationToken can also be obtained using
    // SecurityContextHolder.getContext().getAuthentication()
    final CasAuthenticationToken token = (CasAuthenticationToken) request.getUserPrincipal();
    // proxyTicket could be reused to make calls to the CAS service even if the
    // target url differs
    final String proxyTicket = token.getAssertion().getPrincipal().getProxyTicketFor(targetUrl);

    // Make a remote call using the proxy ticket
    final String serviceUrl = targetUrl+"?ticket="+URLEncoder.encode(proxyTicket, "UTF-8");
    String proxyResponse = CommonUtils.getResponseFromServer(serviceUrl, "UTF-8");
    ...
  }

The CasAuthenticationProvider distinguishes between stateful and stateless clients. A stateful client is considered any that submits to the filterProcessUrl of the CasAuthenticationFilter. A stateless client is any that presents an authentication request to CasAuthenticationFilter on a URL other than the filterProcessUrl.

Because remoting protocols have no way of presenting themselves within the context of an HttpSession, it isn't possible to rely on the default practice of storing the security context in the session between requests. Furthermore, because the CAS server invalidates a ticket after it has been validated by the TicketValidator, presenting the same proxy ticket on subsequent requests will not work.

One obvious option is to not use CAS at all for remoting protocol clients. However, this would eliminate many of the desirable features of CAS. As a middle-ground, the CasAuthenticationProvider uses a StatelessTicketCache. This is used solely for stateless clients which use a principal equal to CasAuthenticationFilter.CAS_STATELESS_IDENTIFIER. What happens is the CasAuthenticationProvider will store the resulting CasAuthenticationToken in the StatelessTicketCache, keyed on the proxy ticket. Accordingly, remoting protocol clients can present the same proxy ticket and the CasAuthenticationProvider will not need to contact the CAS server for validation (aside from the first request). Once authenticated, the proxy ticket could be used for URLs other than the original target service.

This section builds upon the previous sections to accomodate proxy ticket authentication. The first step is to specify to authenticate all artifacts as shown below.

  <bean id="serviceProperties"
        class="org.springframework.security.cas.ServiceProperties">
    ...
    <property name="authenticateAllArtifacts" value="true"/>
  </bean>

The next step is to specify serviceProperties and the authenticationDetailsSource for the CasAuthenticationFilter. The serviceProperties property instructs the CasAuthenticationFilter to attempt to authenticate all artifacts instead of only ones present on the filterProcessUrl. The ServiceAuthenticationDetailsSource creates a ServiceAuthenticationDetails that ensures the current URL, based upon the HttpServletRequest, is used as the service URL when validating the ticket. The method for generating the service URL can be customized by injecting a custom AuthenticationDetailsSource that returns a custom ServiceAuthenticationDetails.

  <bean id="casFilter"
      class="org.springframework.security.cas.web.CasAuthenticationFilter">
    ...
    <property name="serviceProperties" ref="serviceProperties"/>
    <property name="authenticationDetailsSource">
      <bean class=
        "org.springframework.security.cas.web.authentication.ServiceAuthenticationDetailsSource"/>
    </property>
  </bean>

You will also need to update the CasAuthenticationProvider to handle proxy tickets. To do this replace the Cas20ServiceTicketValidator with a Cas20ProxyTicketValidator. You will need to configure the statelessTicketCache and which proxies you want to accept. You can find an example of the updates required to accept all proxies below.

  <bean id="casAuthenticationProvider"
      class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
    ...
    <property name="ticketValidator">
      <bean class="org.jasig.cas.client.validation.Cas20ProxyTicketValidator">
        <constructor-arg value="https://localhost:9443/cas"/>
        <property name="acceptAnyProxy" value="true"/>
      </bean>
    </property>
    <property name="statelessTicketCache">
      <bean class="org.springframework.security.cas.authentication.EhCacheBasedTicketCache">
        <property name="cache">
          <bean class="net.sf.ehcache.Cache"
              init-method="initialise" destroy-method="dispose">
            <constructor-arg value="casTickets"/>
            <constructor-arg value="50"/>
            <constructor-arg value="true"/>
            <constructor-arg value="false"/>
            <constructor-arg value="3600"/>
            <constructor-arg value="900"/>
          </bean>
        </property>
      </bean>
    </property>
  </bean>