diff --git a/docs/manual/src/docbook/anon-auth-provider.xml b/docs/manual/src/docbook/anon-auth-provider.xml index e7469facab..4eae5b058c 100644 --- a/docs/manual/src/docbook/anon-auth-provider.xml +++ b/docs/manual/src/docbook/anon-auth-provider.xml @@ -47,16 +47,17 @@ principal. There is a corresponding AnonymousAuthenticationProvider, which is chained into the ProviderManager so that AnonymousAuthenticationTokens are accepted. Finally, there is an - AnonymousProcessingFilter, which is chained after the normal authentication mechanisms - and automatically adds an AnonymousAuthenticationToken to the + AnonymousAuthenticationFilter, which is chained after the + normal authentication mechanisms and automatically adds an + AnonymousAuthenticationToken to the SecurityContextHolder if there is no existing Authentication held there. The definition of the filter and authentication provider appears as follows: + @@ -68,10 +69,10 @@ The key is shared between the filter and authentication provider, - so that tokens created by the former are accepted by the latter - The use of the key property should not be regarded as - providing any real security here. It is merely a book-keeping exercise. If you - are sharing a ProviderManager which contains an + so that tokens created by the former are accepted by the latterThe use + of the key property should not be regarded as providing any + real security here. It is merely a book-keeping exercise. If you are sharing a + ProviderManager which contains an AnonymousAuthenticationProvider in a scenario where it is possible for an authenticating client to construct the Authentication object (such as with RMI @@ -82,14 +83,15 @@ anonymous provider. This isn't a problem with normal usage but if you are using RMI you would be best to use a customized ProviderManager which omits the anonymous provider rather than sharing the one you use for your - HTTP authentication mechanisms. - . The userAttribute is expressed in the form of + HTTP authentication mechanisms.. The + userAttribute is expressed in the form of usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]. This is the same syntax as used after the equals sign for InMemoryDaoImpl's userMap property. As explained earlier, the benefit of anonymous authentication is that all URI patterns can have security applied to them. For example: - + + @@ -105,31 +107,29 @@ " + ]]> - + +
<interfacename>AuthenticationTrustResolver</interfacename> - - Rounding out the anonymous authentication discussion is the - AuthenticationTrustResolver interface, with its corresponding - AuthenticationTrustResolverImpl implementation. This interface - provides an isAnonymous(Authentication) method, which allows - interested classes to take into account this special type of authentication status. The - ExceptionTranslationFilter uses this interface in processing - AccessDeniedExceptions. If an - AccessDeniedException is thrown, and the authentication is of an + Rounding out the anonymous authentication discussion is the + AuthenticationTrustResolver interface, with its + corresponding AuthenticationTrustResolverImpl implementation. This + interface provides an isAnonymous(Authentication) method, which + allows interested classes to take into account this special type of authentication + status. The ExceptionTranslationFilter uses this interface in + processing AccessDeniedExceptions. If an + AccessDeniedException is thrown, and the authentication is of an anonymous type, instead of throwing a 403 (forbidden) response, the filter will instead commence the AuthenticationEntryPoint so the principal can authenticate properly. This is a necessary distinction, otherwise principals would always be deemed authenticated and never be given an opportunity to login - via form, basic, digest or some other normal authentication mechanism. - - - You will often see the ROLE_ANONYMOUS attribute in the above interceptor configuration - replaced with IS_AUTHENTICATED_ANONYMOUSLY. This is an example of the use of the - AuthenticatedVoter which will see in ???. It uses an - AuthenticationTrustResolver to process this particular configuration - attribute and grant access to aonymous users. + via form, basic, digest or some other normal authentication mechanism. + You will often see the ROLE_ANONYMOUS attribute in the above + interceptor configuration replaced with IS_AUTHENTICATED_ANONYMOUSLY. + This is an example of the use of the AuthenticatedVoter which + will see in ???. It uses an AuthenticationTrustResolver + to process this particular configuration attribute and grant access to aonymous users.
diff --git a/docs/manual/src/docbook/appendix-namespace.xml b/docs/manual/src/docbook/appendix-namespace.xml index b7b76b6dda..ed73b23699 100644 --- a/docs/manual/src/docbook/appendix-namespace.xml +++ b/docs/manual/src/docbook/appendix-namespace.xml @@ -62,7 +62,7 @@ <literal>realm</literal> Sets the realm name used for basic authentication (if enabled). Corresponds to the realmName proerty on - BasicProcessingFilterEntryPoint. + BasicAuthenticationEntryPoint.
<literal>entry-point-ref</literal> @@ -123,7 +123,7 @@ FilterInvocationDefinitionSource used by the FilterSecurityInterceptor and to exclude particular patterns from the filter chain entirely (by setting the attribute filters="none"). It - is also responsible for configuring a ChannelProcessingFilter if + is also responsible for configuring a ChannelAuthenticationFilter if particular URLs need to be accessed by HTTPS, for example.
<literal>pattern</literal> @@ -149,8 +149,8 @@ accessed over HTTP or HTTPS respectively. Alternatively the value "any" can be used when there is no preference. If this attribute is present on any <intercept-url> element, then a - ChannelProcessingFilter will be added to the filter stack and its - additional dependencies added to the application context. + ChannelAuthenticationFilter will be added to the filter stack and + its additional dependencies added to the application context. @@ -237,15 +237,14 @@
The <literal><http-basic></literal> Element - Adds a BasicProcessingFilter and - BasicProcessingFilterEntryPoint to the configuration. The latter - will only be used as the configuration entry point if form-based login is not enabled. - + Adds a BasicAuthenticationFilter and + BasicAuthenticationEntryPoint to the configuration. The latter will + only be used as the configuration entry point if form-based login is not enabled.
The <literal><remember-me></literal> Element - Adds the RememberMeProcessingFilter to the stack. This in turn - will be configured with either a TokenBasedRememberMeServices, a + Adds the RememberMeAuthenticationFilter to the stack. This in + turn will be configured with either a TokenBasedRememberMeServices, a PersistentTokenBasedRememberMeServices or a user-specified bean implementing RememberMeServices depending on the attribute settings. @@ -354,17 +353,17 @@
The <literal><anonymous></literal> Element - Adds an AnonymousProcessingFilter to the stack and an + Adds an AnonymousAuthenticationFilter to the stack and an AnonymousAuthenticationProvider. Required if you are using the IS_AUTHENTICATED_ANONYMOUSLY attribute.
The <literal><x509></literal> Element Adds support for X.509 authentication. An - X509PreAuthenticatedProcessingFilter will be added to the stack and - a PreAuthenticatedProcessingFilterEntryPoint bean will be created. - The latter will only be used if no other authentication mechanisms are in use (it's only - functionality is to return an HTTP 403 error code). A + X509AuthenticationFilter will be added to the stack and an + Http403ForbiddenEntryPoint bean will be created. The latter will + only be used if no other authentication mechanisms are in use (it's only functionality is to + return an HTTP 403 error code). A PreAuthenticatedAuthenticationProvider will also be created which delegates the loading of user authorities to a UserDetailsService. diff --git a/docs/manual/src/docbook/basic-and-digest-auth.xml b/docs/manual/src/docbook/basic-and-digest-auth.xml index 8eec346175..8d2e9b447b 100644 --- a/docs/manual/src/docbook/basic-and-digest-auth.xml +++ b/docs/manual/src/docbook/basic-and-digest-auth.xml @@ -4,20 +4,21 @@ Basic and digest authentiation are alternative authentication mechanisms which are popular in web applications. Basic authentication is often used with stateless clients which pass - their credentials on each request. It's quite common to use it in combination with form-based - authentication where an application is used through both a browser-based user interface - and as a web-service. However, basic authentication transmits the password as plain text so it - should only really be used over an encrypted transport layer such as HTTPS. + their credentials on each request. It's quite common to use it in combination with + form-based authentication where an application is used through both a browser-based user + interface and as a web-service. However, basic authentication transmits the password as + plain text so it should only really be used over an encrypted transport layer such as + HTTPS.
- <classname>BasicProcessingFilter</classname> + <classname>BasicAuthenticationFilter</classname> - BasicProcessingFilter is responsible for processing basic + BasicAuthenticationFilter is responsible for processing basic authentication credentials presented in HTTP headers. This can be used for authenticating calls made by Spring remoting protocols (such as Hessian and Burlap), as well as normal browser user agents (such as Firefox and Internet Explorer). The standard governing HTTP Basic Authentication is defined by RFC 1945, Section 11, and - BasicProcessingFilter conforms with this RFC. Basic + BasicAuthenticationFilter conforms with this RFC. Basic Authentication is an attractive approach to authentication, because it is very widely deployed in user agents and implementation is extremely simple (it's just a Base64 encoding of the username:password, specified in an HTTP header). @@ -26,51 +27,50 @@ Configuration To implement HTTP Basic Authentication, you need to add a - BasicProcessingFilter to your filter chain. The application - context should contain BasicProcessingFilter and its - required collaborator: + BasicAuthenticationFilter to your filter chain. The + application context should contain BasicAuthenticationFilter and + its required collaborator: + + class="org.springframework.security.web.authentication.www.BasicAuthenticationEntryPoint"> ]]> The configured AuthenticationManager processes each authentication request. If authentication fails, the configured - AuthenticationEntryPoint will be used to retry the - authentication process. Usually you will use the filter in combination with a - BasicProcessingFilterEntryPoint, which returns a 401 response + AuthenticationEntryPoint will be used to retry + the authentication process. Usually you will use the filter in combination with a + BasicAuthenticationEntryPoint, which returns a 401 response with a suitable header to retry HTTP Basic authentication. If authentication is - successful, the resulting Authentication object will be - placed into the SecurityContextHolder as usual. + successful, the resulting Authentication object will + be placed into the SecurityContextHolder as usual. If the authentication event was successful, or authentication was not attempted - because the HTTP header did not contain a supported authentication request, the filter - chain will continue as normal. The only time the filter chain will be interrupted is if - authentication fails and the AuthenticationEntryPoint is - called. -
+ because the HTTP header did not contain a supported authentication request, the + filter chain will continue as normal. The only time the filter chain will be + interrupted is if authentication fails and the + AuthenticationEntryPoint is called. +
-
- <classname>DigestProcessingFilter</classname> - DigestProcessingFilter is capable - of processing digest authentication credentials presented in HTTP headers. Digest - Authentication attempts to solve many of the weaknesses of Basic authentication, - specifically by ensuring credentials are never sent in clear text across the wire. Many - user agents support Digest Authentication, including FireFox and Internet Explorer. The - standard governing HTTP Digest Authentication is defined by RFC 2617, which updates an - earlier version of the Digest Authentication standard prescribed by RFC 2069. Most user - agents implement RFC 2617. Spring Security's DigestProcessingFilter is + <classname>DigestAuthenticationFilter</classname> + DigestAuthenticationFilter is capable of processing digest + authentication credentials presented in HTTP headers. Digest Authentication attempts to + solve many of the weaknesses of Basic authentication, specifically by ensuring + credentials are never sent in clear text across the wire. Many user agents support + Digest Authentication, including FireFox and Internet Explorer. The standard governing + HTTP Digest Authentication is defined by RFC 2617, which updates an earlier version of + the Digest Authentication standard prescribed by RFC 2069. Most user agents implement + RFC 2617. Spring Security's DigestAuthenticationFilter is compatible with the "auth" quality of protection - (qop) prescribed by RFC 2617, which also provides backward + (qop) prescribed by RFC 2617, which also provides backward compatibility with RFC 2069. Digest Authentication is a more attractive option if you need to use unencrypted HTTP (i.e. no TLS/HTTPS) and wish to maximise security of the authentication process. Indeed Digest Authentication is a mandatory requirement for the @@ -88,9 +88,9 @@ key: A private key to prevent modification of the nonce token - The DigestProcessingFilterEntryPoint has a property specifying the - key used for generating the nonce tokens, along with a - nonceValiditySeconds property for determining the expiration time + The DigestAuthenticatonEntryPoint has a property specifying the + key used for generating the nonce tokens, along with a + nonceValiditySeconds property for determining the expiration time (default 300, which equals five minutes). Whist ever the nonce is valid, the digest is computed by concatenating various strings including the username, password, nonce, URI being requested, a client-generated nonce (merely a random value which the user agent @@ -98,12 +98,12 @@ server and user agent perform this digest computation, resulting in different hash codes if they disagree on an included value (eg password). In Spring Security implementation, if the server-generated nonce has merely expired (but the digest was otherwise valid), - the DigestProcessingFilterEntryPoint will send a - "stale=true" header. This tells the user agent there is no need + the DigestAuthenticationEntryPoint will send a + "stale=true" header. This tells the user agent there is no need to disturb the user (as the password and username etc is correct), but simply to try again using a new nonce. - An appropriate value for DigestProcessingFilterEntryPoint's - nonceValiditySeconds parameter will depend on your application. + An appropriate value for DigestAuthenticationEntryPoint's + nonceValiditySeconds parameter will depend on your application. Extremely secure applications should note that an intercepted authentication header can be used to impersonate the principal until the expirationTime contained in the nonce is reached. This is the key principle when selecting an @@ -111,28 +111,30 @@ running over TLS/HTTPS in the first instance. Because of the more complex implementation of Digest Authentication, there are often user agent issues. For example, Internet Explorer fails to present an - "opaque" token on subsequent requests in the same session. Spring + "opaque" token on subsequent requests in the same session. Spring Security filters therefore encapsulate all state information into the - "nonce" token instead. In our testing, Spring Security's + "nonce" token instead. In our testing, Spring Security's implementation works reliably with FireFox and Internet Explorer, correctly handling nonce timeouts etc.
- Configuration - Now that we've reviewed the theory, let's see how to use it. To implement HTTP Digest - Authentication, it is necessary to define DigestProcessingFilter in - the fitler chain. The application context will need to define the - DigestProcessingFilter and its required collaborators: + Configuration + Now that we've reviewed the theory, let's see how to use it. To implement HTTP + Digest Authentication, it is necessary to define + DigestAuthenticationFilter in the filter chain. The + application context will need to define the + DigestAuthenticationFilter and its required + collaborators: + - + - + @@ -140,31 +142,31 @@ The configured UserDetailsService is needed because - DigestProcessingFilter must have direct access to the clear text - password of a user. Digest Authentication will NOT work if you are using encoded - passwords in your DAO. The DAO collaborator, along with the - UserCache, are typically shared directly with a - DaoAuthenticationProvider. The - authenticationEntryPoint property must be - DigestProcessingFilterEntryPoint, so that - DigestProcessingFilter can obtain the correct - realmName and key for digest + DigestAuthenticationFilter must have direct access to the + clear text password of a user. Digest Authentication will NOT work if you are using + encoded passwords in your DAO. The DAO collaborator, along with the + UserCache, are typically shared directly with a + DaoAuthenticationProvider. The + authenticationEntryPoint property must be + DigestAuthenticationEntryPoint, so that + DigestAuthenticationFilter can obtain the correct + realmName and key for digest calculations. - Like BasicAuthenticationFilter, if authentication is successful an - Authentication request token will be placed into the - SecurityContextHolder. If the authentication event was - successful, or authentication was not attempted because the HTTP header did not contain - a Digest Authentication request, the filter chain will continue as normal. The only time - the filter chain will be interrupted is if authentication fails and the - AuthenticationEntryPoint is called, as discussed in - the previous paragraph. - Digest Authentication's RFC offers a range of additional features to further increase - security. For example, the nonce can be changed on every request. Despite this, Spring - Security implementation was designed to minimise the complexity of the implementation - (and the doubtless user agent incompatibilities that would emerge), and avoid needing to - store server-side state. You are invited to review RFC 2617 if you wish to explore these - features in more detail. As far as we are aware, Spring Security's implementation does - comply with the minimum standards of this RFC. -
+ Like BasicAuthenticationFilter, if authentication is successful + an Authentication request token will be placed into + the SecurityContextHolder. If the authentication event was + successful, or authentication was not attempted because the HTTP header did not + contain a Digest Authentication request, the filter chain will continue as normal. + The only time the filter chain will be interrupted is if authentication fails and + the AuthenticationEntryPoint is called, as discussed + in the previous paragraph. + Digest Authentication's RFC offers a range of additional features to further + increase security. For example, the nonce can be changed on every request. Despite + this, Spring Security implementation was designed to minimise the complexity of the + implementation (and the doubtless user agent incompatibilities that would emerge), + and avoid needing to store server-side state. You are invited to review RFC 2617 if + you wish to explore these features in more detail. As far as we are aware, Spring + Security's implementation does comply with the minimum standards of this RFC. +
diff --git a/docs/manual/src/docbook/cas-auth-provider.xml b/docs/manual/src/docbook/cas-auth-provider.xml index 30d7e8e3ef..e3a2010ac3 100644 --- a/docs/manual/src/docbook/cas-auth-provider.xml +++ b/docs/manual/src/docbook/cas-auth-provider.xml @@ -1,60 +1,44 @@ - - CAS Authentication -
Overview - - JA-SIG produces an enterprise-wide single sign on system known - as CAS. Unlike other initiatives, JA-SIG's Central Authentication - Service is open source, widely used, simple to understand, platform - independent, and supports proxy capabilities. Spring Security fully - supports CAS, and provides an easy migration path from - single-application deployments of Spring Security through to - multiple-application deployments secured by an enterprise-wide CAS - server. - - You can learn more about CAS at - http://www.ja-sig.org/products/cas/. You will also need - to visit this site to download the CAS Server files. + JA-SIG produces an enterprise-wide single sign on system known as CAS. Unlike other + initiatives, JA-SIG's Central Authentication Service is open source, widely used, simple to + understand, platform independent, and supports proxy capabilities. Spring Security fully + supports CAS, and provides an easy migration path from single-application deployments of + Spring Security through to multiple-application deployments secured by an enterprise-wide CAS + server. + You can learn more about CAS at http://www.ja-sig.org/products/cas/. + You will also need to visit this site to download the CAS Server files.
-
- How CAS Works - - 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 2.0 supports - CAS 3. At the time of writing, the CAS server was at version 3.2. - - 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 displayed - to users. - + + How CAS Works + + 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 2.0 + supports CAS 3. At the time of writing, the CAS server was at version 3.2. + 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 displayed to + users. When deploying a CAS 3.2 server, you will also need to specify an - AuthenticationHandler in the - deployerConfigContext.xml included with CAS. The - AuthenticationHandler has a simple method that - returns a boolean as to whether a given set of Credentials is valid. - Your AuthenticationHandler implementation will need - to link into some type of backend authentication repository, such as - an LDAP server or database. CAS itself includes numerous - AuthenticationHandlers out of the box to assist - with this. When you download and deploy the server war file, it is set up - to successfully authenticate users who 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. This will be explained more fully later. - -
-
- Configuration of CAS Client - - 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 service: - - + Configuration of CAS Client + + 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 service: + + ]]> - - - The service must equal a URL that will be - monitored by the CasProcessingFilter. 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: - - + + 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: + + - + - + ]]> - - - - The CasProcessingFilterEntryPoint should be selected to - drive authentication using entry-point-ref. + - - The CasProcessingFilter has very similar - properties to the UsernamePasswordAuthenticationFilter - (used for form-based logins). Each property is - self-explanatory. Note that we've also used the namespace syntax - for setting up an alias to the authentication mnager, since the - CasProcessingFilter needs a reference to it. - - For CAS to operate, the - ExceptionTranslationFilter must have its - authenticationEntryPoint property set to the - CasProcessingFilterEntryPoint bean. - - The CasProcessingFilterEntryPoint 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 - collaborators: - 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). Each + property is self-explanatory. Note that we've also used the namespace syntax for setting up an + alias to the authentication mnager, since the CasAuthenticationFilter needs + a reference to it. + For CAS to operate, the ExceptionTranslationFilter must have its + authenticationEntryPoint property set to the + CasAuthenticationEntryPoint bean. + 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 collaborators: @@ -355,16 +324,14 @@ ... ]]> - - The CasAuthenticationProvider uses a UserDetailsService - instance to load the authorities for a user, once they have been authentiated by CAS. We've shown a simple - in-memory setup here. - - - The beans are all reasonable self-explanatory if you refer back - to the "How CAS Works" section. + The + CasAuthenticationProvider uses a + UserDetailsService instance to load the authorities for a + user, once they have been authentiated by CAS. We've shown a simple in-memory setup here. + The beans are all reasonable self-explanatory if you refer back to the "How CAS Works" + section.
- - \ No newline at end of file + diff --git a/docs/manual/src/docbook/core-filters.xml b/docs/manual/src/docbook/core-filters.xml index e10705fe20..67e07aada4 100644 --- a/docs/manual/src/docbook/core-filters.xml +++ b/docs/manual/src/docbook/core-filters.xml @@ -250,15 +250,15 @@ class="org.springframework.security.web.context.SecurityContextPersistenceFilter ExceptionTranslationFilter. Implement the login page (using a JSP or MVC controller).Configure an instance of - UsernamePasswordAuthenticationFilter in - the application contextAdd the filter bean - to your filter chain proxy (making sure you pay attention to the order). + UsernamePasswordAuthenticationFilter in the + application contextAdd the filter bean to + your filter chain proxy (making sure you pay attention to the order). The login form simply contains j_username and j_password input fields, and posts to the URL that is monitored by the filter (by default this is /j_spring_security_check). The basic filter configuration looks something like this: diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index fdbdeb35b5..e8af5a3f4c 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -188,7 +188,7 @@ authentication and logout handling services respectively In versions prior to 3.0, this list also included remember-me functionality. This could cause some confusing errors with some configurations and was removed in 3.0. In 3.0, the addition - of an AnonymousProcessingFilter is part of the default + of an AnonymousAuthenticationFilter is part of the default <http> configuration, so the <anonymous /> element is added regardless of whether auto-config is enabled. . They each have attributes which can be used to alter @@ -472,39 +472,37 @@ align="center">AliasFilter ClassNamespace Element or Attribute - CHANNEL_FILTERChannelProcessingFilterhttp/intercept-url + CHANNEL_FILTERChannelProcessingFilterhttp/intercept-url@requires-channel CONCURRENT_SESSION_FILTERConcurrentSessionFilter - http/concurrent-session-control - SESSION_CONTEXT_INTEGRATION_FILTERHttpSessionContextIntegrationFilterhttp + session-management/concurrency-control + SECURITY_CONTEXT_FILTERSecurityContextPersistenceFilterhttp LOGOUT_FILTER LogoutFilterhttp/logout X509_FILTER - X509PreAuthenticatedProcessigFilterhttp/x509 + X509AuthenticationFilterhttp/x509 PRE_AUTH_FILTER AstractPreAuthenticatedProcessingFilter - SubclassesN/A CAS_PROCESSING_FILTER - CasProcessingFilterN/A - AUTHENTICATION_PROCESSING_FILTER + SubclassesN/A CAS_FILTER + CasAuthenticationFilterN/A + FORM_LOGIN_FILTER UsernamePasswordAuthenticationFilterhttp/form-login - BASIC_PROCESSING_FILTER - BasicProcessingFilterhttp/http-basic - SERVLET_API_SUPPORT_FILTERSecurityContextHolderAwareRequestFilterhttp/@servlet-api-provision + BASIC_AUTH_FILTER + BasicAuthenticationFilterhttp/http-basic + SERVLET_API_SUPPORT_FILTERSecurityContextHolderAwareFilterhttp/@servlet-api-provision REMEMBER_ME_FILTER - RememberMeProcessingFilterhttp/remember-me + RememberMeAuthenticationFilterhttp/remember-me ANONYMOUS_FILTER - AnonymousProcessingFilterhttp/anonymous - EXCEPTION_TRANSLATION_FILTER + AnonymousAuthenticationFilterhttp/anonymous + SESSION_MANAGEMENT_FILTERSessionManagementFiltersession-managementEXCEPTION_TRANSLATION_FILTER ExceptionTranslationFilterhttp - NTLM_FILTER - NtlmProcessingFilterN/A FILTER_SECURITY_INTERCEPTOR FilterSecurityInterceptorhttp SWITCH_USER_FILTER - SwitchUserProcessingFilterN/A + SwitchUserFilterN/A You can add your own filter to the stack, using the custom-filter element and one of these names to specify the position your filter should appear at: - + diff --git a/docs/manual/src/docbook/preauth.xml b/docs/manual/src/docbook/preauth.xml index ac3b4cbb25..762264749f 100644 --- a/docs/manual/src/docbook/preauth.xml +++ b/docs/manual/src/docbook/preauth.xml @@ -8,150 +8,137 @@ has already been reliably authenticated by some external system prior to accessing the application. We refer to these situations as pre-authenticated scenarios. Examples include X.509, Siteminder and authentication by the J2EE container in which the - application is running. When using pre-authentication, Spring Security has to - - - Identify the user making the request. - - - Obtain the authorities for the user. - - The details will depend on the external authentication mechanism. A user might be - identified by their certificate information in the case of X.509, or by an HTTP request header - in the case of Siteminder. If relying on container authentication, the user will be identified - by calling the getUserPrincipal() method on the incoming HTTP request. - In some cases, the external mechanism may supply role/authority information for the user but in - others the authorities must be obtained from a separate source, such as a - UserDetailsService. - + application is running. When using pre-authentication, Spring Security has to + Identify the user making the request. + Obtain the authorities for the + user.The details will depend on the external authentication + mechanism. A user might be identified by their certificate information in the case of X.509, or + by an HTTP request header in the case of Siteminder. If relying on container authentication, the + user will be identified by calling the getUserPrincipal() method on the + incoming HTTP request. In some cases, the external mechanism may supply role/authority + information for the user but in others the authorities must be obtained from a separate source, + such as a UserDetailsService.
Pre-Authentication Framework Classes - Because most pre-authentication mechanisms follow the same pattern, Spring - Security has a set of classes which provide an internal framework for implementing - pre-authenticated authentication providers. This removes duplication and allows new - implementations to be added in a structured fashion, without having to write everything from - scratch. You don't need to know about these classes if you want to use something like - X.509 authentication, as it already has a namespace configuration - option which is simpler to use and get started with. If you need to use explicit bean confiuration or - are planning on writing your own implementation then an understanding of how the - provided implementations work will be useful. You will find classes under the - org.springframework.security.web.authentication.preauth. We just provide an outline - here so you should consult the Javadoc and source where appropriate. - - + Because most pre-authentication mechanisms follow the same pattern, Spring Security has a + set of classes which provide an internal framework for implementing pre-authenticated + authentication providers. This removes duplication and allows new implementations to be added + in a structured fashion, without having to write everything from scratch. You don't need to + know about these classes if you want to use something like X.509 + authentication, as it already has a namespace configuration option which is simpler + to use and get started with. If you need to use explicit bean confiuration or are planning on + writing your own implementation then an understanding of how the provided implementations work + will be useful. You will find classes under the + org.springframework.security.web.authentication.preauth. We just provide + an outline here so you should consult the Javadoc and source where appropriate.
AbstractPreAuthenticatedProcessingFilter - - This class will check the current contents of the security context and, if empty, it will attempt to extract - user information from the HTTP request and submit it to the AuthenticationManager. - Subclasses override the following methods to obtain this information: - + This class will check the current contents of the security context and, if empty, it + will attempt to extract user information from the HTTP request and submit it to the + AuthenticationManager. Subclasses override the following + methods to obtain this information: + protected abstract Object getPreAuthenticatedPrincipal(HttpServletRequest request); protected abstract Object getPreAuthenticatedCredentials(HttpServletRequest request); - After calling these, the filter will create a PreAuthenticatedAuthenticationToken - containing the returned data and submit it for authentication. By authentication here, we - really just mean further processing to perhaps load the user's authorities, but the standard Spring Security - authentication architecture is followed. - + After calling these, the filter will create a + PreAuthenticatedAuthenticationToken containing the returned data + and submit it for authentication. By authentication here, we really just mean + further processing to perhaps load the user's authorities, but the standard Spring Security + authentication architecture is followed.
-
AbstractPreAuthenticatedAuthenticationDetailsSource - - Like other Spring Security authentication filters, the pre-authentication filter has an - authenticationDetailsSource property which by default will create a - WebAuthenticationDetails object to store additional information such as - the session-identifier and originating IP address in the details property of - the Authentication object. - In cases where user role information can be obtained from the pre-authentication mechanism, the - data is also stored in this property. Subclasses of - AbstractPreAuthenticatedAuthenticationDetailsSource use an extended details - object which implements the GrantedAuthoritiesContainer interface, thus enabling the - authentication provider to read the authorities which were externally allocated to the user. We'll look at a concrete - example next. - + Like other Spring Security authentication filters, the pre-authentication filter has an + authenticationDetailsSource property which by default will create a + WebAuthenticationDetails object to store additional information + such as the session-identifier and originating IP address in the details + property of the Authentication object. In cases where user + role information can be obtained from the pre-authentication mechanism, the data is also + stored in this property. Subclasses of + AbstractPreAuthenticatedAuthenticationDetailsSource use an extended + details object which implements the + GrantedAuthoritiesContainer interface, thus enabling the + authentication provider to read the authorities which were externally allocated to the user. + We'll look at a concrete example next.
J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource - - If the filter is configured with an authenticationDetailsSource which is an instance of this - class, the authority information is obtained by calling the isUserInRole(String role) method - for each of a pre-determined set of mappable roles. The class gets these from a configured - MappableAttributesRetriever. Possible implementations include hard-coding a list in the application - context and reading the role information from the <security-role> information in a - web.xml file. The pre-authentication sample application uses the latter approach. - - There is an additional stage where the roles (or attributes) are mapped to Spring Security - GrantedAuthority objects using a configured - Attributes2GrantedAuthoritiesMapper. The default will just add the usual ROLE_ - prefix to the names, but it gives you full control over the behaviour. - + If the filter is configured with an authenticationDetailsSource + which is an instance of this class, the authority information is obtained by calling the + isUserInRole(String role) method for each of a pre-determined + set of mappable roles. The class gets these from a configured + MappableAttributesRetriever. Possible implementations + include hard-coding a list in the application context and reading the role information + from the <security-role> information in a + web.xml file. The pre-authentication sample application uses the + latter approach. + There is an additional stage where the roles (or attributes) are mapped to Spring + Security GrantedAuthority objects using a configured + Attributes2GrantedAuthoritiesMapper. The default will + just add the usual ROLE_ prefix to the names, but it gives you full + control over the behaviour.
PreAuthenticatedAuthenticationProvider - - The pre-authenticated provider has little more to do than load the UserDetails - object for the user. It does this by delegating to a AuthenticationUserDetailsService. - The latter is similar to the standard UserDetailsService but takes an - Authentication object rather than just user name: - + The pre-authenticated provider has little more to do than load the + UserDetails object for the user. It does this by delegating + to a AuthenticationUserDetailsService. The latter is similar + to the standard UserDetailsService but takes an + Authentication object rather than just user name: + public interface AuthenticationUserDetailsService { UserDetails loadUserDetails(Authentication token) throws UsernameNotFoundException; } - - This interface may have also other uses but with pre-authentication it allows access to the authorities which - were packaged in the Authentication object, as we saw in the previous section. - The PreAuthenticatedGrantedAuthoritiesUserDetailsService class does this. - Alternatively, it may delegate to a standard UserDetailsService via the - UserDetailsByNameServiceWrapper implementation. - + + This interface may have also other uses but with pre-authentication it allows access to the + authorities which were packaged in the Authentication object, + as we saw in the previous section. The + PreAuthenticatedGrantedAuthoritiesUserDetailsService class does + this. Alternatively, it may delegate to a standard + UserDetailsService via the + UserDetailsByNameServiceWrapper implementation.
Http403ForbiddenEntryPoint - - The AuthenticationEntryPoint was discussed in the technical - overview chapter. Normally it is responsible for kick-starting the authentication process for an unauthenticated user - (when they try to access a protected resource), but in the pre-authenticated case this doesn't apply. You would only - configure the ExceptionTranslationFilter with an instance of this class if you aren't - using pre-authentication in combination with other authentication mechanisms. - It will be called if the user is rejected by the AbstractPreAuthenticatedProcessingFilter - resulting in a null authentication. It always returns a 403-forbidden response code if called. - + The AuthenticationEntryPoint was discussed in the technical overview chapter. Normally it + is responsible for kick-starting the authentication process for an unauthenticated user + (when they try to access a protected resource), but in the pre-authenticated case this + doesn't apply. You would only configure the + ExceptionTranslationFilter with an instance of this class if you + aren't using pre-authentication in combination with other authentication mechanisms. It will + be called if the user is rejected by the + AbstractPreAuthenticatedProcessingFilter resulting in a null + authentication. It always returns a 403-forbidden response code if + called.
-
Concrete Implementations - - X.509 authentication is covered in its own chapter. Here we'll look at some classes - which provide support for other pre-authenticated scenarios. - - + X.509 authentication is covered in its own chapter. Here + we'll look at some classes which provide support for other pre-authenticated scenarios.
Request-Header Authentication (Siteminder) - - An external authentication system may supply information to the application by setting specific headers on the HTTP request. - A well known example of this is is Siteminder, which passes the username in a header called SM_USER. - This mechanism is supported by the class RequestHeaderPreAuthenticatedProcessingFilter which - simply extracts the username from the header. It defaults to using the name SM_USER as the - header name. See the Javadoc for more details. - + An external authentication system may supply information to the application by setting + specific headers on the HTTP request. A well known example of this is is Siteminder, which + passes the username in a header called SM_USER. This mechanism is + supported by the class RequestHeaderAuthenticationFilter which simply + extracts the username from the header. It defaults to using the name + SM_USER as the header name. See the Javadoc for more details. - Note that when using a system like this, the framework performs no authentication checks at all and - it is extremely important that the external system is configured properly and protects all - access to the application. If an attacker is able to forge the headers in their original request without this being - detected then they could potentially choose any userame they wished. - + Note that when using a system like this, the framework performs no authentication + checks at all and it is extremely important that the external system + is configured properly and protects all access to the application. If an attacker is able + to forge the headers in their original request without this being detected then they could + potentially choose any userame they wished.
Siteminder Example Configuration - - A typical configuration using this filter would look like this: - A typical configuration using this filter would look like this: +"org.springframework.security.web.authentication.preauth.header.RequestHeaderAuthenticationFilter"> @@ -170,30 +157,27 @@ class="org.springframework.security.web.authentication.preauth.PreAuthenticatedA ]]> - - We've assumed here that the security namespace is being used for configuration (hence the user of the custom-filter, - authentication-manager and custom-authentication-provider elements (you can read more about them - in the namespace chapter). You would leave these out of a traditional bean configuration. - It's also assumed that you have added a UserDetailsService (called userDetailsService) - to your configuration to load the user's roles. + We've assumed here that the security namespace is being used for + configuration (hence the user of the custom-filter, + authentication-manager and + custom-authentication-provider elements (you can read more about them + in the namespace chapter). You would leave these out + of a traditional bean configuration. It's also assumed that you have added a + UserDetailsService (called + userDetailsService) to your configuration to load the user's roles.
-
J2EE Container Authentication - - The class J2eePreAuthenticatedProcessingFilter will extract the username from the - userPrincipal property of the HttpServletRequest. use of this - filter would usually be combined with the use of J2EE roles as described above in . - - - There is a sample application in the codebase which uses this approach, so get hold of the code from subversion and - have a look at the application context file if you are interested. The code is in the samples/preauth - directory. - - + The class J2eePreAuthenticatedProcessingFilter will extract the + username from the userPrincipal property of the + HttpServletRequest. use of this filter would usually be + combined with the use of J2EE roles as described above in . + There is a sample application in the codebase which uses this approach, so get hold of + the code from subversion and have a look at the application context file if you are + interested. The code is in the samples/preauth directory.
- diff --git a/docs/manual/src/docbook/remember-me-authentication.xml b/docs/manual/src/docbook/remember-me-authentication.xml index 0815cb0af6..494e61f9fe 100644 --- a/docs/manual/src/docbook/remember-me-authentication.xml +++ b/docs/manual/src/docbook/remember-me-authentication.xml @@ -1,34 +1,33 @@ - Remember-Me Authentication - - -
- Overview - - Remember-me or persistent-login authentication refers to web sites being able to - remember the identity of a principal between sessions. This is - typically accomplished by sending a cookie to the browser, with the - cookie being detected during future sessions and causing automated - login to take place. Spring Security provides the necessary hooks for - these operations to take place, and has two concrete - remember-me implementations. One uses hashing to preserve the security of - cookie-based tokens and the other uses a database or other persistent storage - mechanism to store the generated tokens. - - Note that both implemementations require a UserDetailsService. - If you are using an authentication provider which doesn't use a UserDetailsService - (for example, the LDAP provider) then it won't work unless you also have a UserDetailsService - bean in your application context. - -
- + + Remember-Me Authentication + +
+ + Overview + + Remember-me or persistent-login authentication refers to web sites being able to + remember the identity of a principal between sessions. This is typically accomplished by + sending a cookie to the browser, with the cookie being detected during future sessions + and causing automated login to take place. Spring Security provides the necessary hooks + for these operations to take place, and has two concrete remember-me implementations. + One uses hashing to preserve the security of cookie-based tokens and the other uses a + database or other persistent storage mechanism to store the generated tokens. + Note that both implemementations require a + UserDetailsService. If you are using an + authentication provider which doesn't use a + UserDetailsService (for example, the LDAP provider) + then it won't work unless you also have a + UserDetailsService bean in your application context. + +
Simple Hash-Based Token Approach - This approach uses hashing to achieve a useful remember-me strategy. - In essence a cookie is sent to the browser upon successful interactive authentication, with the + This approach uses hashing to achieve a useful remember-me strategy. In essence a + cookie is sent to the browser upon successful interactive authentication, with the cookie being composed as follows: - + base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key)) @@ -38,109 +37,101 @@ expressed in milliseconds key: A private key to prevent modification of the remember-me token - As such the remember-me token is valid only for the period - specified, and provided that the username, password and key does not - change. Notably, this has a potential security issue in that a - captured remember-me token will be usable from any user agent until - such time as the token expires. This is the same issue as with digest - authentication. If a principal is aware a token has been captured, - they can easily change their password and immediately invalidate all - remember-me tokens on issue. If more significant security is - needed you should use the approach described in the next section. Alternatively - remember-me services should simply not be used at all. - - If you are familiar with the topics discussed in the chapter on namespace configuration, - you can enable remember-me authentication just by adding the <remember-me> element: - As such the remember-me token is valid only for the period specified, and provided + that the username, password and key does not change. Notably, this has a potential + security issue in that a captured remember-me token will be usable from any user agent + until such time as the token expires. This is the same issue as with digest + authentication. If a principal is aware a token has been captured, they can easily + change their password and immediately invalidate all remember-me tokens on issue. If + more significant security is needed you should use the approach described in the next + section. Alternatively remember-me services should simply not be used at all. + If you are familiar with the topics discussed in the chapter on namespace configuration, you can enable remember-me + authentication just by adding the <remember-me> element: ... ]]> - - The UserDetailsService will normally be selected automatically. If you have more than one in - your application context, you need to specify which one should be used with the user-service-ref attribute, - where the value is the name of your UserDetailsService bean. - + The UserDetailsService will + normally be selected automatically. If you have more than one in your application + context, you need to specify which one should be used with the + user-service-ref attribute, where the value is the name of your + UserDetailsService bean.
-
Persistent Token Approach - This approach is based on the article - http://jaspan.com/improved_persistent_login_cookie_best_practice - with some minor modifications Essentially, the username is not included in the cookie, to prevent exposing a valid login - name unecessarily. There is a discussion on this in the comments section of this article.. - To use the this approach with namespace configuration, you would supply a datasource reference: - This approach is based on the article http://jaspan.com/improved_persistent_login_cookie_best_practice with some + minor modifications Essentially, the username is not included in the + cookie, to prevent exposing a valid login name unecessarily. There is a + discussion on this in the comments section of this article.. + To use the this approach with namespace configuration, you would supply a datasource + reference: ... ]]> - - The database should contain a persistent_logins table, created using the following SQL (or equivalent): - + The database should contain a + persistent_logins table, created using the following SQL (or + equivalent): + create table persistent_logins (username varchar(64) not null, series varchar(64) primary key, token varchar(64) not null, last_used timestamp not null) - - + -
- -
- Remember-Me Interfaces and Implementations - - Remember-me authentication is not used with basic - authentication, given it is often not used with - HttpSessions. Remember-me is used with - UsernamePasswordAuthenticationFilter, and is implemented - via hooks in the AbstractAuthenticationProcessingFilter - superclass. The hooks will invoke a concrete - RememberMeServices at the appropriate times. The - interface looks like this: - +
+
+ + Remember-Me Interfaces and Implementations + + Remember-me authentication is not used with basic authentication, given it is often + not used with HttpSessions. Remember-me is used with + UsernamePasswordAuthenticationFilter, and is implemented via + hooks in the AbstractAuthenticationProcessingFilter superclass. The + hooks will invoke a concrete RememberMeServices at the + appropriate times. The interface looks like this: + Authentication autoLogin(HttpServletRequest request, HttpServletResponse response); void loginFail(HttpServletRequest request, HttpServletResponse response); void loginSuccess(HttpServletRequest request, HttpServletResponse response, Authentication successfulAuthentication); - Please refer to the JavaDocs for a fuller discussion on what the - methods do, although note at this stage that - AbstractAuthenticationProcessingFilter only calls the - loginFail() and loginSuccess() - methods. The autoLogin() method is called by - RememberMeProcessingFilter whenever the - SecurityContextHolder does not contain an - Authentication. This interface therefore provides - the underlying remember-me implementation with sufficient - notification of authentication-related events, and delegates to the - implementation whenever a candidate web request might contain a cookie - and wish to be remembered. This design allows any number of remember-me implementation - strategies. We've seen above that Spring Security provides - two implementations. We'll look at thes in turn. - + Please refer to the JavaDocs for a fuller discussion on what the methods do, although + note at this stage that AbstractAuthenticationProcessingFilter only + calls the loginFail() and loginSuccess() methods. + The autoLogin() method is called by + RememberMeAuthenticationFilter whenever the + SecurityContextHolder does not contain an + Authentication. This interface therefore provides the + underlying remember-me implementation with sufficient notification of + authentication-related events, and delegates to the implementation whenever a candidate + web request might contain a cookie and wish to be remembered. This design allows any + number of remember-me implementation strategies. We've seen above that Spring Security + provides two implementations. We'll look at thes in turn.
TokenBasedRememberMeServices - - This implementation supports the simpler approach described in . - TokenBasedRememberMeServices generates a - RememberMeAuthenticationToken, which is processed - by RememberMeAuthenticationProvider. A - key is shared between this authentication provider - and the TokenBasedRememberMeServices. In addition, - TokenBasedRememberMeServices requires A - UserDetailsService from which it can retrieve the username and - password for signature comparison purposes, and generate the - RememberMeAuthenticationToken to contain the - correct GrantedAuthority[]s. Some sort of logout - command should be provided by the application that invalidates the cookie if - the user requests this. TokenBasedRememberMeServices also implements Spring Security's - LogoutHandler interface so can be used with LogoutFilter - to have the cookie cleared automatically. - - The beans required in an application context to enable remember-me services are as follows: - + This implementation supports the simpler approach described in . + TokenBasedRememberMeServices generates a + RememberMeAuthenticationToken, which is processed by + RememberMeAuthenticationProvider. A key is + shared between this authentication provider and the + TokenBasedRememberMeServices. In addition, + TokenBasedRememberMeServices requires A UserDetailsService + from which it can retrieve the username and password for signature comparison + purposes, and generate the RememberMeAuthenticationToken to + contain the correct GrantedAuthority[]s. Some sort of + logout command should be provided by the application that invalidates the cookie if + the user requests this. TokenBasedRememberMeServices also + implements Spring Security's LogoutHandler interface + so can be used with LogoutFilter to have the cookie cleared + automatically. + The beans required in an application context to enable remember-me services are as + follows: @@ -157,27 +148,26 @@ ]]> Don't forget to add your - RememberMeServices implementation to your - UsernamePasswordAuthenticationFilter.setRememberMeServices() - property, include the - RememberMeAuthenticationProvider in your - AuthenticationManager.setProviders() list, and add - RememberMeProcessingFilter into your - FilterChainProxy (typically immediately after your - UsernamePasswordAuthenticationFilter). + RememberMeServices implementation to your + UsernamePasswordAuthenticationFilter.setRememberMeServices() + property, include the RememberMeAuthenticationProvider in your + AuthenticationManager.setProviders() list, and add + RememberMeAuthenticationFilter into your + FilterChainProxy (typically immediately after your + UsernamePasswordAuthenticationFilter).
PersistentTokenBasedRememberMeServices - - This class can be used in the same way as TokenBasedRememberMeServices, but it additionally - needs to be configured with a PersistentTokenRepository to store the tokens. - There are two standard implementations. - - InMemoryTokenRepositoryImpl which is intended for testing only. - JdbcTokenRepositoryImpl which stores the tokens in a database. - - The database schema is described above in . - + This class can be used in the same way as + TokenBasedRememberMeServices, but it additionally needs + to be configured with a PersistentTokenRepository to + store the tokens. There are two standard implementations. + InMemoryTokenRepositoryImpl + which is intended for testing + only.JdbcTokenRepositoryImpl + which stores the tokens in a database. + The database schema is described above in .
- \ No newline at end of file + diff --git a/docs/manual/src/docbook/security-filter-chain.xml b/docs/manual/src/docbook/security-filter-chain.xml index 4001170b77..aa68bf33d5 100644 --- a/docs/manual/src/docbook/security-filter-chain.xml +++ b/docs/manual/src/docbook/security-filter-chain.xml @@ -6,27 +6,27 @@ Spring Security's web infrastructure is based entirely on standard servlet filters. It doesn't use servlets or any other servlet-based frameworks (such as Spring MVC) internally, so it has no strong links to any particular web technology. It deals in - HttpServletRequests and HttpServletResponses - and doesn't care whether the requests come from a browser, a web service client, an + HttpServletRequests and HttpServletResponses and + doesn't care whether the requests come from a browser, a web service client, an HttpInvoker or an AJAX application. Spring Security maintains a filter chain internally where each of the filters has a particular responsibility and filters are added or removed from the configuration depending on - which services are required. The ordering of the filters is important as there are - dependencies between them. If you have been using namespace - configuration, then the filters are automatically configured for you and you don't - have to define any Spring beans explicitly but here may be times when you want full control - over the security filter chain, either because you are using features which aren't supported - in the namespace, or you are using your own customized versions of classes. + which services are required. The ordering of the filters is important as there are dependencies + between them. If you have been using namespace + configuration, then the filters are automatically configured for you and you don't have + to define any Spring beans explicitly but here may be times when you want full control over the + security filter chain, either because you are using features which aren't supported in the + namespace, or you are using your own customized versions of classes.
<classname>DelegatingFilterProxy</classname> When using servlet filters, you obviously need to declare them in your web.xml, or they will be ignored by the servlet container. In Spring - Security, the filter classes are also Spring beans defined in the application context and - thus able to take advantage of Spring's rich dependency-injection facilities and lifecycle + Security, the filter classes are also Spring beans defined in the application context and thus + able to take advantage of Spring's rich dependency-injection facilities and lifecycle interfaces. Spring's DelegatingFilterProxy provides the link between web.xml and the application context. - When using DelegatingFilterProxy, you will see something like - this in the web.xml file: When using DelegatingFilterProxy, you will see something like this + in the web.xml file: myFilter org.springframework.web.filter.DelegatingFilterProxy @@ -37,11 +37,11 @@ /* ]]> Notice that the filter is actually a - DelegatingFilterProxy, and not the class that will actually implement - the logic of the filter. What DelegatingFilterProxy does is delegate - the Filter's methods through to a bean which is obtained from - the Spring application context. This enables the bean to benefit from the Spring web - application context lifecycle support and configuration flexibility. The bean must implement + DelegatingFilterProxy, and not the class that will actually implement the + logic of the filter. What DelegatingFilterProxy does is delegate the + Filter's methods through to a bean which is obtained from the + Spring application context. This enables the bean to benefit from the Spring web application + context lifecycle support and configuration flexibility. The bean must implement javax.servlet.Filter and it must have the same name as that in the filter-name element. Read the Javadoc for DelegatingFilterProxy for more information @@ -50,11 +50,11 @@ <classname>FilterChainProxy</classname> It should now be clear that you can declare each Spring Security filter bean that you require in your application context file and add a corresponding - DelegatingFilterProxy entry to web.xml for - each filter, making sure that they are ordered correctly. This is a cumbersome approach and + DelegatingFilterProxy entry to web.xml for each + filter, making sure that they are ordered correctly. This is a cumbersome approach and clutters up the web.xml file quickly if we have a lot of filters. We - would prefer to just add a single entry to web.xml and deal entirely - with the application context file for managing our web security beans. This is where Spring + would prefer to just add a single entry to web.xml and deal entirely with + the application context file for managing our web security beans. This is where Spring Secuiryt's FilterChainProxy comes in. It is wired using a DelegatingFilterProxy, just like in the example above, but with the filter-name set to the bean name filterChainProxy. The @@ -64,24 +64,24 @@ ]]> - The namespace element filter-chain-map is - used to set up the security filter chain(s) which are required within the application - Note that you'll need to include the security namespace in your application context - XML file in order to use this syntax. - . It maps a particular URL pattern to a chain of filters built up from the bean - names specified in the filters element. Both regular expressions and Ant - Paths are supported, and the most specific URIs appear first. At runtime the + The namespace element filter-chain-map is used + to set up the security filter chain(s) which are required within the + applicationNote that you'll need to include the security namespace in your + application context XML file in order to use this syntax.. It maps a + particular URL pattern to a chain of filters built up from the bean names specified in the + filters element. Both regular expressions and Ant Paths are supported, + and the most specific URIs appear first. At runtime the FilterChainProxy will locate the first URI pattern that matches the current web request and the list of filter beans specified by the filters attribute will be applied to that request. The filters will be invoked in the order they are @@ -89,112 +89,92 @@ URL. You may have noticed we have declared two SecurityContextPersistenceFilters in the filter chain - (ASC is short for allowSessionCreation, a property - of SecurityContextPersistenceFilter). As web services will never - present a jsessionid on future requests, creating - HttpSessions for such user agents would be wasteful. If you had a - high-volume application which required maximum scalability, we recommend you use the - approach shown above. For smaller applications, using a single - SecurityContextPersistenceFilter (with its default + (ASC is short for allowSessionCreation, a property of + SecurityContextPersistenceFilter). As web services will never present + a jsessionid on future requests, creating HttpSessions + for such user agents would be wasteful. If you had a high-volume application which required + maximum scalability, we recommend you use the approach shown above. For smaller applications, + using a single SecurityContextPersistenceFilter (with its default allowSessionCreation as true) would likely be sufficient. In relation to lifecycle issues, the FilterChainProxy will always delegate init(FilterConfig) and destroy() - methods through to the underlaying Filters if such methods - are called against FilterChainProxy itself. In this case, + methods through to the underlaying Filters if such methods are + called against FilterChainProxy itself. In this case, FilterChainProxy guarantees to only initialize and destroy each Filter bean once, no matter how many times it is declared in the filter - chain(s). You control the overall choice as to whether these methods are called or not via - the targetFilterLifecycle initialization parameter of + chain(s). You control the overall choice as to whether these methods are called or not via the + targetFilterLifecycle initialization parameter of DelegatingFilterProxy. By default this property is false and servlet container lifecycle invocations are not delegated through DelegatingFilterProxy. - When we looked at how to set up web security using namespace configuration, we used a - DelegatingFilterProxy with the name - springSecurityFilterChain. You should now be able to see that this is the + When we looked at how to set up web security using namespace configuration, we used a DelegatingFilterProxy with the + name springSecurityFilterChain. You should now be able to see that this is the name of the FilterChainProxy which is created by the namespace.
Bypassing the Filter Chain - As with the namespace, you can use the attribute filters = "none" - as an alternative to supplying a filter bean list. This will omit the request pattern from - the security filter chain entirely. Note that anything matching this path will then have - no authentication or authorization services applied and will be freely accessible. If you - want to make use of the contents of the SecurityContext contents - during a request, then it must have passed through the security filter chain. Otherwise - the SecurityContextHolder will not have been populated and the - contents will be null. + As with the namespace, you can use the attribute filters = "none" as + an alternative to supplying a filter bean list. This will omit the request pattern from the + security filter chain entirely. Note that anything matching this path will then have no + authentication or authorization services applied and will be freely accessible. If you want + to make use of the contents of the SecurityContext contents during a + request, then it must have passed through the security filter chain. Otherwise the + SecurityContextHolder will not have been populated and the contents + will be null.
Filter Ordering The order that filters are defined in the chain is very important. Irrespective of which - filters you are actually using, the order should be as follows: - - - ChannelProcessingFilter, because it might need to redirect - to a different protocol - - - ConcurrentSessionFilter, because it doesn't use any - SecurityContextHolder functionality but needs to update the - SessionRegistry to reflect ongoing requests from the - principal - - - SecurityContextPersistenceFilter, so a - SecurityContext can be set up in the + filters you are actually using, the order should be as follows: + ChannelProcessingFilter, because + it might need to redirect to a different + protocolConcurrentSessionFilter, + because it doesn't use any SecurityContextHolder functionality + but needs to update the SessionRegistry to reflect + ongoing requests from the + principalSecurityContextPersistenceFilter, + so a SecurityContext can be set up in the SecurityContextHolder at the beginning of a web request, and any changes to the SecurityContext can be copied to the - HttpSession when the web request ends (ready for use with the - next web request) - - - Authentication processing mechanisms - + HttpSession when the web request ends (ready for use with the next + web request)Authentication processing mechanisms - UsernamePasswordAuthenticationFilter, - CasProcessingFilter, - BasicProcessingFilter etc - so that the + CasAuthenticationFilter, + BasicAuthenticationFilter etc - so that the SecurityContextHolder can be modified to contain a valid - Authentication request token - - - The SecurityContextHolderAwareRequestFilter, if you are using - it to install a Spring Security aware HttpServletRequestWrapper - into your servlet container - - - RememberMeProcessingFilter, so that if no earlier - authentication processing mechanism updated the + Authentication request + tokenThe + SecurityContextHolderAwareRequestFilter, if you are using it to + install a Spring Security aware HttpServletRequestWrapper into your + servlet + containerRememberMeAuthenticationFilter, + so that if no earlier authentication processing mechanism updated the SecurityContextHolder, and the request presents a cookie that enables remember-me services to take place, a suitable remembered - Authentication object will be put there - - - AnonymousProcessingFilter, so that if no earlier - authentication processing mechanism updated the + Authentication object will be put + thereAnonymousAuthenticationFilter, + so that if no earlier authentication processing mechanism updated the SecurityContextHolder, an anonymous - Authentication object will be put there - - - ExceptionTranslationFilter, to catch any Spring Security - exceptions so that either an HTTP error response can be returned or an appropriate - AuthenticationEntryPoint can be launched - - - FilterSecurityInterceptor, to protect web URIs and raise - exceptions when access is denied - - + Authentication object will be put + thereExceptionTranslationFilter, + to catch any Spring Security exceptions so that either an HTTP error response can be + returned or an appropriate AuthenticationEntryPoint can + be + launchedFilterSecurityInterceptor, + to protect web URIs and raise exceptions when access is + denied
Use with other Filter-Based Frameworks - If you're using some other framework that is also filter-based, then you need to make - sure that the Spring Security filters come first. This enables the + If you're using some other framework that is also filter-based, then you need to make sure + that the Spring Security filters come first. This enables the SecurityContextHolder to be populated in time for use by the other filters. Examples are the use of SiteMesh to decorate your web pages or a web framework like Wicket which uses a filter to handle its requests.
-