diff --git a/docs/manual/src/docbook/cas-auth-provider.xml b/docs/manual/src/docbook/cas-auth-provider.xml index cc0682cd56..63f5b728b1 100644 --- a/docs/manual/src/docbook/cas-auth-provider.xml +++ b/docs/manual/src/docbook/cas-auth-provider.xml @@ -18,7 +18,7 @@ Whilst the CAS web site contains documents that detail the architecture of CAS, we present the general overview again here within the context of Spring Security. Spring Security - 3.0 supports CAS 3. At the time of writing, the CAS server was at version 3.4. + 3.x supports CAS 3. At the time of writing, the CAS server was at version 3.4. Somewhere in your enterprise you will need to setup a CAS server. The CAS server is simply a standard WAR file, so there isn't anything difficult about setting up your server. Inside the WAR file you will customise the login and other single sign on pages @@ -35,8 +35,9 @@ enter a password matching their username, which is useful for testing. Apart from the CAS server itself, the other key players are of course the secure web applications deployed throughout your enterprise. These web applications are known as - "services". There are two types of services: standard services and proxy services. A proxy - service is able to request resources from other services on behalf of the user. + "services". There are three types of services. Those that authenticate service tickets, those that + can obtain proxy tickets, and those that authenticate proxy tickets. Authenticating a proxy ticket + differs because the list of proxies must be validated and often times a proxy ticket can be reused.
Spring Security and CAS Interaction Sequence @@ -119,14 +120,14 @@ CasAuthenticationProvider will validate the service ticket using a - TicketValidator implementation. This will typically be a - Cas20ServiceTicketValidator ticket which is one of the classes - included in the CAS client library. The Cas20ServiceTicketValidator - makes an HTTPS request to the CAS server in order to validate the service ticket. + TicketValidator implementation. This will typically be a + Cas20ServiceTicketValidator which is one of the classes + included in the CAS client library. In the event the application needs to validate proxy tickets, the + Cas20ProxyTicketValidator is used. The + TicketValidator makes an HTTPS request to the CAS server in order to + validate the service ticket. + @@ -211,10 +212,17 @@ The web application side of CAS is made easy due to Spring Security. It is assumed you already know the basics of using Spring Security, so these are not covered again below. We'll assume a namespace based configuration is being used and add in the CAS beans as - required. - You will need to add a ServiceProperties bean to your - application context. This represents your CAS service: - CAS sample application can be found in the Spring + Security Samples. +
+ + Service Ticket Authentication + + This section describes how to setup Spring Security to authenticate Service Tickets. You will need + to add a ServiceProperties bean to your application context. This represents + your CAS service: + ]]> - 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): - + 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): + ... - - + + - - - + + + - - - - + + + + ]]> - The CasAuthenticationEntryPoint should be selected to drive - authentication using entry-point-ref. - The CasAuthenticationFilter has very similar properties to the - UsernamePasswordAuthenticationFilter (used for form-based - logins). For CAS to operate, the ExceptionTranslationFilter must have its authenticationEntryPoint property set to the - CasAuthenticationEntryPoint bean. - The CasAuthenticationEntryPoint must refer 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. - Next you need to add a CasAuthenticationProvider and its + 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: @@ -269,7 +276,11 @@ - + + + + + @@ -286,104 +297,110 @@ 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. - The beans are all reasonably self-explanatory if you refer back to the - How CAS Works section. - This completes the configuration of 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. + here. Note that the CasAuthenticationProvider does not actually use + the password for authentication. + 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. +
+
+ + Proxy Ticket Authentication + + 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. + + ... + + +]]> + 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. + ... + + + + + +]]> + 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. + + ... + + + + + + + + + + + + + + + + + + + + + +]]> +
- - -