diff --git a/docs/manual/src/docbook/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml index 1769affb7d..fb1ece045a 100644 --- a/docs/manual/src/docbook/springsecurity.xml +++ b/docs/manual/src/docbook/springsecurity.xml @@ -97,8 +97,23 @@ Security. - - + + + + + + Web Application Security + + + Most Spring Security users will be using the framework in enterprise applications which + make user of the HTTP and the Servlet API. In this part we'll take a look at how Spring Security provides + authentication and access-control features for the web layer of an application. We'll look + behind the facade of the namespace and see which classes and interfaces are actually assembled to provide web-layer + security. In some situations it is necessary to use traditional bean configuration to provide full control over + the configuration, so we'll also see how to configure these classes directly without the namespace. + + + Authentication diff --git a/docs/manual/src/docbook/supporting-infrastructure.xml b/docs/manual/src/docbook/supporting-infrastructure.xml index 8f640ef224..a005f9bf7c 100644 --- a/docs/manual/src/docbook/supporting-infrastructure.xml +++ b/docs/manual/src/docbook/supporting-infrastructure.xml @@ -1,97 +1,32 @@ - + - Supporting Infrastructure - - - This chapter introduces some of the supplementary and supporting - infrastructure used by Spring Security. If a capability is not directly - related to security, yet included in the Spring Security project, we - will discuss it in this chapter. - -
- Localization - Spring Security supports localization of exception messages that - end users are likely to see. If your application is designed for - English users, you don't need to do anything as by default all - Security Security messages are in English. If you need to support - other locales, everything you need to know is contained in this - section. - - All exception messages can be localized, including messages - related to authentication failures and access being denied - (authorization failures). Exceptions and logging that is focused on - developers or system deployers (including incorrect attributes, - interface contract violations, using incorrect constructors, startup - time validation, debug-level logging) etc are not localized and - instead are hard-coded in English within Spring Security's - code. - - Shipping in the spring-security-core-xx.jar you - will find an org.springframework.security package - that in turn contains a messages.properties file. - This should be referred to by your - ApplicationContext, as Spring Security classes - implement Spring's MessageSourceAware interface and - expect the message resolver to be dependency injected at application - context startup time. Usually all you need to do is register a bean - inside your application context to refer to the messages. An example - is shown below: - - - - -]]> - - The messages.properties is named in - accordance with standard resource bundles and represents the default - language supported by Spring Security messages. This default file is - in English. If you do not register a message source, Spring Security - will still work correctly and fallback to hard-coded English versions - of the messages. - - If you wish to customize the - messages.properties file, or support other - languages, you should copy the file, rename it accordingly, and - register it inside the above bean definition. There are not a large - number of message keys inside this file, so localization should not be - considered a major initiative. If you do perform localization of this - file, please consider sharing your work with the community by logging - a JIRA task and attaching your appropriately-named localized version - of messages.properties. - - Rounding out the discussion on localization is the Spring - ThreadLocal known as - org.springframework.context.i18n.LocaleContextHolder. - You should set the LocaleContextHolder to represent - the preferred Locale of each user. Spring Security - will attempt to locate a message from the message source using the - Locale obtained from this - ThreadLocal. Please refer to Spring documentation - for further details on using LocaleContextHolder - and the helper classes that can automatically set it for you (eg - AcceptHeaderLocaleResolver, - CookieLocaleResolver, - FixedLocaleResolver, - SessionLocaleResolver etc) -
+ Web Security Infrastructure
- Filters + Spring Security Filters - Spring Security uses many filters, as referred to throughout the - remainder of this reference guide. If you are using namespace configuration, - then the you don't usually have to declare the filter beans explicitly. There 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. - In this case, you have a choice in how these filters are added to your web application, in that you can use either - Spring's DelegatingFilterProxy or - FilterChainProxy. We'll look at both below. - - When using DelegatingFilterProxy, you will see - something like this in the web.xml file: - + Spring Security's web application features are implemented using 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 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 + 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. + +
+ <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 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: + myFilter @@ -103,132 +38,111 @@ /* ]]> - - Notice that the filter is actually a DelegatingFilterProxy, - and not the filter 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. - - There is a lifecycle issue to consider when hosting - Filters in an IoC container instead of a servlet - container. Specifically, which container should be responsible for - calling the Filter's "startup" and "shutdown" - methods? It is noted that the order of initialization and destruction - of a Filter can vary by servlet container, and this - can cause problems if one Filter depends on - configuration settings established by an earlier initialized - Filter. The Spring IoC container on the other hand - has more comprehensive lifecycle/IoC interfaces (such as - InitializingBean, - DisposableBean, BeanNameAware, - ApplicationContextAware and many others) as well as - a well-understood interface contract, predictable method invocation - ordering, autowiring support, and even options to avoid implementing - Spring interfaces (eg the destroy-method attribute - in Spring XML). For this reason we recommend the use of Spring - lifecycle services instead of servlet container lifecycle services - wherever possible. Read the Javadoc for DelegatingFilterProxy - for more information - - Rather than using DelegatingFilterProxy, we - strongly recommend that you use FilterChainProxy instead. - Whilst DelegatingFilterProxy is a very useful class, - the problem is that the number of lines of code required for - <filter> and - <filter-mapping> entries in - web.xml explodes when using more than a few - filters. To overcome this issue, Spring Security provides a - FilterChainProxy class. It is wired using a - DelegatingFilterProxy (just like in the example above), - but the target class is - org.springframework.security.web.FilterChainProxy. - The filter chain is then declared in the application context, using - code such as this: - - 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 +
+
+ <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 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 Secuiryt's FilterChainProxy comes in. It is wired using a DelegatingFilterProxy + (just like in the example above), but the target class is org.springframework.security.web.FilterChainProxy. + The filter chain is then declared in the application context. Here's an example: + ]]> - - - You may notice similarities with the way - FilterSecurityInterceptor is declared. 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 defined, so you have complete control over the filter chain - which is applied to a particular URL. - - You may have noticed we have declared two - HttpSessionContextIntegrationFilters in the filter - chain (ASC is short for - allowSessionCreation, a property of - HttpSessionContextIntegrationFilter). 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 - HttpSessionContextIntegrationFilter (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, FilterChainProxy guarantees to only - initialize and destroy each Filter once, - irrespective of how many times it is declared by the - FilterInvocationDefinitionSource. You control the - overall choice as to whether these methods are called or not via the - targetFilterLifecycle initialization parameter of the - DelegatingFilterProxy that proxies - DelegatingFilterProxy. As discussed above, by default - any servlet container lifecycle invocations are not delegated through - to DelegatingFilterProxy. - - You can use the attribute filters = "none" - in the same way that you do when using namespace configuration - to build the FilterChainProxy. 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. - - The order that filters are defined in web.xml + + The namespace element filter-chain-map is used to set up the security filter chain(s) which are required + within the application. 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 defined, so you have complete control over the filter chain + which is applied to a particular 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 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, 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 + 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 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. + +
+
+ +
+ Filter Ordering + The order that filters are defined in the chain is very important. Irrespective of which filters you are actually - using, the order of the <filter-mapping>s - should be as follows: + using, the order should be as follows: - ChannelProcessingFilter, because it might + ChannelProcessingFilter, because it might need to redirect to a different protocol - ConcurrentSessionFilter, because it + ConcurrentSessionFilter, because it doesn't use any SecurityContextHolder functionality but needs to update the SessionRegistry to reflect ongoing requests @@ -236,7 +150,7 @@ - HttpSessionContextIntegrationFilter, so a + SecurityContextPersistenceFilter, so a SecurityContext can be setup in the SecurityContextHolder at the beginning of a web request, and any changes to the SecurityContext @@ -246,10 +160,9 @@ Authentication processing mechanisms - - UsernamePasswordAuthenticationProcessingFilter, - CasProcessingFilter, - BasicProcessingFilter, HttpRequestIntegrationFilter, - JbossIntegrationFilter etc - so that the + UsernamePasswordAuthenticationProcessingFilter, + CasProcessingFilter, + BasicProcessingFilter etc - so that the SecurityContextHolder can be modified to contain a valid Authentication request token @@ -274,7 +187,7 @@ - AnonymousProcessingFilter, so that if no + AnonymousProcessingFilter, so that if no earlier authentication processing mechanism updated the SecurityContextHolder, an anonymous Authentication object will be put there @@ -292,21 +205,20 @@ URIs - - All of the above filters use - DelegatingFilterProxy or - FilterChainProxy. It is recommended that a single - DelegatingFilterProxy proxy through to a single - FilterChainProxy for each application, with that - FilterChainProxy defining all of Spring Security - filters. - - If you're using SiteMesh, ensure Spring Security filters execute - before the SiteMesh filters are called. This enables the - SecurityContextHolder to be populated in time for - use by SiteMesh decorators +
+ +
+ Use with other Filter-Based Frameworks + If you're using SiteMesh, ensure Spring Security filters execute + before the SiteMesh filters are called. This enables the + SecurityContextHolder to be populated in time for + use by SiteMesh decorators. + +
+ +
Tag Libraries diff --git a/docs/manual/src/docbook/technical-overview.xml b/docs/manual/src/docbook/technical-overview.xml index af3a18e20e..d98baa72fb 100644 --- a/docs/manual/src/docbook/technical-overview.xml +++ b/docs/manual/src/docbook/technical-overview.xml @@ -580,4 +580,67 @@ Successfully authenticated. Security context contains: \
+
+ Localization + Spring Security supports localization of exception messages that + end users are likely to see. If your application is designed for + English-speaking users, you don't need to do anything as by default all + Security Security messages are in English. If you need to support + other locales, everything you need to know is contained in this + section. + + All exception messages can be localized, including messages + related to authentication failures and access being denied + (authorization failures). Exceptions and logging that is focused on + developers or system deployers (including incorrect attributes, + interface contract violations, using incorrect constructors, startup + time validation, debug-level logging) etc are not localized and + instead are hard-coded in English within Spring Security's + code. + + Shipping in the spring-security-core-xx.jar you + will find an org.springframework.security package + that in turn contains a messages.properties file. + This should be referred to by your + ApplicationContext, as Spring Security classes + implement Spring's MessageSourceAware interface and + expect the message resolver to be dependency injected at application + context startup time. Usually all you need to do is register a bean + inside your application context to refer to the messages. An example + is shown below: + + + + +]]> + + The messages.properties is named in + accordance with standard resource bundles and represents the default + language supported by Spring Security messages. This default file is + in English. If you do not register a message source, Spring Security + will still work correctly and fallback to hard-coded English versions + of the messages. + + If you wish to customize the + messages.properties file, or support other + languages, you should copy the file, rename it accordingly, and + register it inside the above bean definition. There are not a large + number of message keys inside this file, so localization should not be + considered a major initiative. If you do perform localization of this + file, please consider sharing your work with the community by logging + a JIRA task and attaching your appropriately-named localized version + of messages.properties. + + Rounding out the discussion on localization is the Spring + ThreadLocal known as + org.springframework.context.i18n.LocaleContextHolder. + You should set the LocaleContextHolder to represent + the preferred Locale of each user. Spring Security + will attempt to locate a message from the message source using the + Locale obtained from this + ThreadLocal. Please refer to the Spring Framework documentation + for further details on using LocaleContextHolder. +