From be12d93f7ac35c5fc5283c5cb33af4ece7a7ece7 Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Mon, 6 Jul 2009 10:33:14 +0000 Subject: [PATCH] Manual updates --- .../manual/src/docbook/anon-auth-provider.xml | 99 +++++-- docs/manual/src/docbook/core-filters.xml | 271 +++++++++--------- docs/manual/src/docbook/core-services.xml | 35 ++- docs/manual/src/docbook/dao-auth-provider.xml | 176 +++++------- docs/manual/src/docbook/namespace-config.xml | 59 ++-- docs/manual/src/docbook/springsecurity.xml | 8 +- .../manual/src/docbook/technical-overview.xml | 55 ++-- 7 files changed, 382 insertions(+), 321 deletions(-) diff --git a/docs/manual/src/docbook/anon-auth-provider.xml b/docs/manual/src/docbook/anon-auth-provider.xml index 52de4015b9..e7469facab 100644 --- a/docs/manual/src/docbook/anon-auth-provider.xml +++ b/docs/manual/src/docbook/anon-auth-provider.xml @@ -6,31 +6,49 @@ Overview - Particularly in the case of web request URI security, sometimes it is more convenient - to assign configuration attributes against every possible secure object invocation. Put - differently, sometimes it is nice to say ROLE_SOMETHING is required - by default and only allow certain exceptions to this rule, such as for login, logout and - home pages of an application. There are also other situations where anonymous - authentication would be desired, such as when an auditing interceptor queries the - SecurityContextHolder to identify which principal was - responsible for a given operation. Such classes can be authored with more robustness if - they know the SecurityContextHolder always contains an - Authentication object, and never + It's generally considered good security practice to adopt a + deny-by-default where you explicitly specify what is allowed and + disallow everything else. Defining what is accessible to unauthenticated users is a + similar situation, particularly for web applications. Many sites require that users must + be authenticated for anything other than a few URLs (for example the home and login + pages). In this case it is easiest to define access configuration attributes for these + specific URLs rather than have for every secured resource. Put differently, sometimes it + is nice to say ROLE_SOMETHING is required by default and only allow + certain exceptions to this rule, such as for login, logout and home pages of an + application. You could also omit these pages from the filter chain entirely, thus + bypassing the access control checks, but this may be undesirable for other reasons, + particularly if the pages behave differently for authenticated users. + This is what we mean by anonymous authentication. Note that there is no real + conceptual difference between a user who is anonymously authenticated and + an unauthenticated user. Spring Security's anonymous authentication just gives you a + more convenient way to configure your access-control attributes. Calls to servlet API + calls such as getCallerPrincipal, for example, will still + return null even though there is actually an anonymous authentication object in the + SecurityContextHolder. + There are other situations where anonymous authentication is useful, such as when an + auditing interceptor queries the SecurityContextHolder to + identify which principal was responsible for a given operation. Classes can be authored + more robustly if they know the SecurityContextHolder always + contains an Authentication object, and never null.
Configuration - Spring Security provides three classes that together provide an anonymous - authentication feature. AnonymousAuthenticationToken is an - implementation of Authentication, and stores the - GrantedAuthority[]s which apply to the anonymous + Anonymous authentication support is provided automatically when using the HTTP + configurain Spring Security 3.0 and can be customized (or disabled) using the + <anonymous> element. You don't need to configure the beans + described here unless you are using traditional bean configuration. + Three classes that together provide the anonymous authentication feature. + AnonymousAuthenticationToken is an implementation of + Authentication, and stores the + GrantedAuthoritys which apply to the anonymous principal. There is a corresponding AnonymousAuthenticationProvider, which is chained into the ProviderManager so that - AnonymousAuthenticationTokens are accepted. Finally, there is an + AnonymousAuthenticationTokens are accepted. Finally, there is an AnonymousProcessingFilter, which is chained after the normal authentication mechanisms - and automatically add an AnonymousAuthenticationToken to the + 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: @@ -50,8 +68,22 @@ The key is shared between the filter and authentication provider, - so that tokens created by the former are accepted by the latter. The - userAttribute is expressed in the form of + 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 + AnonymousAuthenticationProvider in a scenario where + it is possible for an authenticating client to construct the + Authentication object (such as with RMI + invocations), then a malicious client could submit an + AnonyousAuthenticationToken which it had created + itself (with chosen username and authority list). If the key + is guessable or can be found out, then the token would be accepted by the + 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 usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]. This is the same syntax as used after the equals sign for InMemoryDaoImpl's userMap property. @@ -59,7 +91,7 @@ can have security applied to them. For example: @@ -73,18 +105,31 @@ " + ]]> - Rounding out the anonymous authentication discussion is the - AuthenticationTrustResolver interface, with its corresponding - AuthenticationTrustResolverImpl implementation. This interface + +
+
+ <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 + 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 + 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. +
diff --git a/docs/manual/src/docbook/core-filters.xml b/docs/manual/src/docbook/core-filters.xml index 1936456465..6f6892d653 100644 --- a/docs/manual/src/docbook/core-filters.xml +++ b/docs/manual/src/docbook/core-filters.xml @@ -86,7 +86,7 @@ /secure/ pattern. If they were reversed, the /secure/ pattern would always match and the /secure/super/ pattern would never be evaluated. - +-->
<classname>ExceptionTranslationFilter</classname> - The ExceptionTranslationFilter sits above the FilterSecurityInterceptor - in the security filter stack. It doesn't do any actual security enforcement itself, - but handles exceptions thrown by the security interceptors and provides suitable - and HTTP responses. - The ExceptionTranslationFilter sits above the + FilterSecurityInterceptor in the security filter stack. It + doesn't do any actual security enforcement itself, but handles exceptions thrown by the + security interceptors and provides suitable and HTTP responses. @@ -121,22 +120,20 @@ class="org.springframework.security.web.access.AccessDeniedHandlerImpl"> -]]> - +]]>
<interfacename>AuthenticationEntryPoint</interfacename> - - The AuthenticationEntryPoint will be - called if the user requests a secure HTTP resource but they are not authenticated. An - appropriate AuthenticationException or - AccessDeniedException will be thrown by a security - interceptor further down the call stack, triggering the - commence method on the entry point. This does the job of - presenting the appropriate response to the user so that authentication can begin. The - one we've used here is LoginUrlAuthenticationEntryPoint, which - redirects the request to a different URL (typically a login page). The actual - implementation used will depend on the authentication mechanism you want to be used in - your application. + The AuthenticationEntryPoint will be called if the + user requests a secure HTTP resource but they are not authenticated. An appropriate + AuthenticationException or + AccessDeniedException will be thrown by a + security interceptor further down the call stack, triggering the + commence method on the entry point. This does the job + of presenting the appropriate response to the user so that authentication can begin. + The one we've used here is LoginUrlAuthenticationEntryPoint, + which redirects the request to a different URL (typically a login page). The actual + implementation used will depend on the authentication mechanism you want to be used + in your application.
<interfacename>AccessDeniedHandler</interfacename> @@ -156,65 +153,69 @@ for which they don't have enough permissions. In this case, ExceptionTranslationFilter will invoke a second strategy, the AccessDeniedHandler. By default, an - AccessDeniedHandlerImpl is used, which just sends a 403 (Forbidden) - response to the client. Alternatively you can configure an instance explicitly (as in - the above example) and set an error page URL which it will forwards the request to - We use a forward so that the SecurityContextHolder still contains details of the principal, - which may be useful for displaying to the user. In old releases of Spring Security we relied upon the servlet - container to handle a 403 error message, which lacked this useful contextual information.. - This can be a simple access denied page, such as a JSP, or it could be - a more complex handler such as an MVC controller. And of course, you can implement the - interface yourself and use your own implementation. - - It's also possible to supply a custom AccessDeniedHandler when you're - using the namespace to configure your application. See . + AccessDeniedHandlerImpl is used, which just sends a 403 + (Forbidden) response to the client. Alternatively you can configure an instance + explicitly (as in the above example) and set an error page URL which it will + forwards the request to + We use a forward so that the SecurityContextHolder still contains details + of the principal, which may be useful for displaying to the user. In old + releases of Spring Security we relied upon the servlet container to handle a + 403 error message, which lacked this useful contextual information. + . This can be a simple access denied page, such as a JSP, + or it could be a more complex handler such as an MVC controller. And of course, you + can implement the interface yourself and use your own implementation. + It's also possible to supply a custom + AccessDeniedHandler when you're using the + namespace to configure your application. See .
<classname>SecurityContextPersistenceFilter</classname> - - We covered the purpose of this all-important filter in so - you might want to re-read that section at this point. Let's first take a look at how you would configure it - for use with a FilterChainProxy. A basic configuration only requires the bean itself - We covered the purpose of this all-important filter in so you might want to re-read + that section at this point. Let's first take a look at how you would configure it + for use with a FilterChainProxy. A basic configuration only + requires the bean itself - ]]> - As we saw previously, this filter has two main tasks. It is responsible for storage of the SecurityContext - contents between HTTP requests and for clearing the SecurityContextHolder when a request is completed. - Clearing the ThreadLocal in which the context is stored is essential, as it might otherwise be possible for - a thread to be replaced into the servlet container's thread pool, with the security context for a particular user still - attached. This thread might then be used at a later stage, performing operations with the wrong credentials. - - + ]]> As we saw previously, this filter has two main tasks. It is responsible for + storage of the SecurityContext contents between HTTP requests + and for clearing the SecurityContextHolder when a request is + completed. Clearing the ThreadLocal in which the context is + stored is essential, as it might otherwise be possible for a thread to be replaced + into the servlet container's thread pool, with the security context for a particular + user still attached. This thread might then be used at a later stage, performing + operations with the wrong credentials.
<interfacename>SecurityContextRepository</interfacename> - From Spring Security 3.0, the job of loading and storing the security context is now delegated - to a separate strategy interface: - + From Spring Security 3.0, the job of loading and storing the security context + is now delegated to a separate strategy interface: + public interface SecurityContextRepository { SecurityContext loadContext(HttpRequestResponseHolder requestResponseHolder); void saveContext(SecurityContext context, HttpServletRequest request, HttpServletResponse response); } - - The HttpRequestResponseHolder is simply a container for the incoming request and - response objects, allowing the implementation to replace these with wrapper classes. The - returned contents will be passed to the filter chain. - - - The default implementation is HttpSessionSecurityContextRepository, which - stores the security context as an HttpSession attribute - In Spring Security 2.0 and earlier, this filter was called - HttpSessionContextIntegrationFilter and performed all the work of - storing the context was performed by the filter itself. If you were familiar with this class, - then most of the configuration options which were available can now be found on - HttpSessionSecurityContextRepository. - . - The most important configuration parameter for this implementation is the - allowSessionCreation property, which defaults to true, thus - allowing the class to create a session if it needs one to store the security context for an authenticated - user (it won't create one unless authentication has taken place and the contents of the security context have changed). - If you don't want a session to be created, then you can set this property to false: - + The HttpRequestResponseHolder is simply a container for + the incoming request and response objects, allowing the implementation to + replace these with wrapper classes. The returned contents will be passed to the + filter chain. + The default implementation is + HttpSessionSecurityContextRepository, which stores + the security context as an HttpSession attribute + In Spring Security 2.0 and earlier, this filter was called + HttpSessionContextIntegrationFilter and + performed all the work of storing the context was performed by the + filter itself. If you were familiar with this class, then most of the + configuration options which were available can now be found on + HttpSessionSecurityContextRepository. + . The most important configuration parameter for this implementation + is the allowSessionCreation property, which defaults to + true, thus allowing the class to create a session if it + needs one to store the security context for an authenticated user (it won't + create one unless authentication has taken place and the contents of the + security context have changed). If you don't want a session to be created, then + you can set this property to false: @@ -223,83 +224,89 @@ public interface SecurityContextRepository { - ]]> - - Alternatively you could provide a null implementation of the SecurityContextRepository interface. - + ]]> Alternatively you could provide a null implementation of the + SecurityContextRepository interface.
<classname>UsernamePasswordAuthenticationProcessingFilter</classname> - We've now seen the three main filters which are always present in a Spring Security web configuration. These - are also the three which are automatically created by the namespace <http> element and - cannot be substituted with alternatives. The only thing that's missing now is an actual authentication mechanism, something - that will allow a user to authenticate. This filter is the most commonly used authentication filter and the one - that is most often customized - For historical reasons, prior to Spring Security 3.0, this filter was called - AuthenticationProcessingFilter and the entry point was called - AuthenticationProcessingFilterEntryPoint. Since the framework now supports - many different forms of authentication, they have both been given more specific names in 3.0.. - It also provides the implementation used by the <form-login> element from the namespace. - There are three stages required to configure it. - - Configure a LoginUrlAuthenticationEntryPoint with the URL - of the login page, just as we did above, and set it on the ExceptionTranslationFilter. - + We've now seen the three main filters which are always present in a Spring + Security web configuration. These are also the three which are automatically created + by the namespace <http> element and cannot be substituted + with alternatives. The only thing that's missing now is an actual authentication + mechanism, something that will allow a user to authenticate. This filter is the most + commonly used authentication filter and the one that is most often customized + For historical reasons, prior to Spring Security 3.0, this filter was + called AuthenticationProcessingFilter and the entry + point was called + AuthenticationProcessingFilterEntryPoint. Since + the framework now supports many different forms of authentication, they have + both been given more specific names in 3.0. + . It also provides the implementation used by the <form-login> + element from the namespace. There are three stages required to configure it. + + Configure a LoginUrlAuthenticationEntryPoint + with the URL of the login page, just as we did above, and set it on the + ExceptionTranslationFilter. - Implement the login page (using a JSP or MVC controller). - Configure an instance of UsernamePasswordAuthenticationProcessingFilter in the application context - Add the filter bean to your filter chain proxy (making sure you pay attention to the order). - - The login form simply contains j_username and + + Implement the login page (using a JSP or MVC controller). + + + Configure an instance of + UsernamePasswordAuthenticationProcessingFilter + in the application context + + + Add 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: - /j_spring_security_check). The basic filter configuration + looks something like this: ]]> - - - +
Application Flow on Authentication Success and Failure - - The filter calls the configured AuthenticationManager - processes each authentication request. The destination following a successful authentication - or an authentication failure is controlled by the AuthenticationSuccessHandler - and AuthenticationFailureHandler strategy interfaces, respectively. - The filter has properties which allow you to set these so you can customize the behaviour as - much as you want - In versions prior to 3.0, the application flow at this point had evolved to a stage - was controlled by a mix of properties on this class and strategy plugins. The - decision was made for 3.0 to refactor the code to make these two strategies entirely responsible. - . - Some standard implementations are supplied such as - SimpleUrlAuthenticationSuccessHandler, - SavedRequestAwareAuthenticationSuccessHandler, - SimpleUrlAuthenticationFailureHandler and - ExceptionMappingAuthenticationFailureHandler. Have a look at the Javadoc - for these classes to see how they work. - - + The filter calls the configured + AuthenticationManager to process each + authentication request. The destination following a successful authentication or + an authentication failure is controlled by the + AuthenticationSuccessHandler and + AuthenticationFailureHandler strategy + interfaces, respectively. The filter has properties which allow you to set these + so you can customize the behaviour completely + In versions prior to 3.0, the application flow at this point had + evolved to a stage was controlled by a mix of properties on this class + and strategy plugins. The decision was made for 3.0 to refactor the code + to make these two strategies entirely responsible. + . Some standard implementations are supplied such as + SimpleUrlAuthenticationSuccessHandler, + SavedRequestAwareAuthenticationSuccessHandler, + SimpleUrlAuthenticationFailureHandler and + ExceptionMappingAuthenticationFailureHandler. Have a + look at the Javadoc for these classes to see how they work. If authentication is successful, the resulting - Authentication object will be placed into the - SecurityContextHolder. - The configured AuthenticationSuccessHandler will then be called to either redirect or forward - the user to the approprate destination. By default a SavedRequestAwareAuthenticationSuccessHandler - is used, which means that the user will be redirected to the original destination they requested before they were asked to - login. - - - The ExceptionTranslationFilter caches the original request a user makes. - When the user authenticates, the request handler makes use of this cached request to obtain the original - URL and redirect to it. The original request is then rebuilt and used as an alternative. - - - If authentication fails, the configured AuthenticationFailureHandler will be invoked. + Authentication object will be placed into the + SecurityContextHolder. The configured + AuthenticationSuccessHandler will then be called to either redirect or forward + the user to the approprate destination. By default a + SavedRequestAwareAuthenticationSuccessHandler is + used, which means that the user will be redirected to the original destination + they requested before they were asked to login. + The ExceptionTranslationFilter caches the + original request a user makes. When the user authenticates, the request + handler makes use of this cached request to obtain the original URL and + redirect to it. The original request is then rebuilt and used as an + alternative. + If authentication fails, the configured + AuthenticationFailureHandler will be invoked.
diff --git a/docs/manual/src/docbook/core-services.xml b/docs/manual/src/docbook/core-services.xml index f95282604a..7f7571e246 100644 --- a/docs/manual/src/docbook/core-services.xml +++ b/docs/manual/src/docbook/core-services.xml @@ -27,17 +27,15 @@ chapter and refresh your memory. The most common approach to verifying an authentication request is to load the corresponding UserDetails and check the loaded password against the one that has been entered by the user. This is the - approach used by the DaoAuthenticationProvider, which wraps a - UserDetailsService to implement an - AuthenticationProvider. The loaded - UserDetails object - and particularly the + approach used by the DaoAuthenticationProvider (see below). The + loaded UserDetails object - and particularly the GrantedAuthoritys it contains - will be used when building the fully populated Authentication object which is returned from a successful authentication and stored in the SecurityContext. If you are using the namespace, an instance of ProviderMananger is created and maintained internally, and - you add providers to it either by using the namespace authentication provired elements, + you add providers to it either by using the namespace authentication provider elements, or by adding the <custom-authentication-provider> element to a bean (see the namespace chapter). In this case, you should not declare a ProviderManager bean in your @@ -76,6 +74,33 @@ concerned about this, because if you forget to register a suitable provider, you'll simply receive a ProviderNotFoundException when an attempt to authenticate is made. +
+ <literal>DaoAuthenticationProvider</literal> + The simplest AuthenticationProvider implemented by + Spring Security is DaoAuthenticationProvider, which is is also + one of the earliest supported by the framework. It leverages a + UserDetailsService (as a DAO) in order to lookup + the username, password and GrantedAuthoritys. It + authenticates the user simply by comparing the password submitted in a + UsernamePasswordAuthenticationToken against the one + loaded by the UserDetailsService. Configuring the + provider is quite simple: + + + + +]]> + The PasswordEncoder and SaltSource are + optional. A PasswordEncoder provides encoding and decoding of passwords + presented in the UserDetails object that is returned from the configured + UserDetailsService. A SaltSource enables + the passwords to be populated with a "salt", which enhances the security of the + passwords in the authentication repository. These will be discussed in more detail in ???. + + +
<interfacename>UserDetailsService</interfacename> Implementations diff --git a/docs/manual/src/docbook/dao-auth-provider.xml b/docs/manual/src/docbook/dao-auth-provider.xml index 46019d9995..f8cd3a9737 100644 --- a/docs/manual/src/docbook/dao-auth-provider.xml +++ b/docs/manual/src/docbook/dao-auth-provider.xml @@ -1,36 +1,34 @@ - -DAO Authentication Provider - -
- Overview - - Spring Security includes a production-quality - AuthenticationProvider implementation called - DaoAuthenticationProvider. This authentication - provider is compatible with all of the authentication mechanisms that - generate a UsernamePasswordAuthenticationToken, and - is probably the most commonly used provider in the framework. Like - most of the other authentication providers, the - DaoAuthenticationProvider leverages a UserDetailsService in order to - lookup the username, password and GrantedAuthority[]s. Unlike most of - the other authentication providers that leverage UserDetailsService, - this authentication provider actually requires the password to be - presented, and the provider will actually evaluate the validity or - otherwise of the password presented in an authentication request - object. -
- -
- Configuration - - Aside from adding DaoAuthenticationProvider to your - ProviderManager list (as discussed at the start of this part of the - reference guide), and ensuring a suitable authentication mechanism is - configured to present a UsernamePasswordAuthenticationToken, the - configuration of the provider itself is rather simple: - - + + DAO Authentication Provider + +
+ + Overview + + Spring Security includes a production-quality + AuthenticationProvider implementation called + DaoAuthenticationProvider. This authentication provider is + compatible with all of the authentication mechanisms that generate a + UsernamePasswordAuthenticationToken, and is probably the most + commonly used provider in the framework. Like most of the other authentication + providers, the DaoAuthenticationProvider leverages a UserDetailsService in order to + lookup the username, password and GrantedAuthority[]s. Unlike most of the other + authentication providers that leverage UserDetailsService, this authentication provider + actually requires the password to be presented, and the provider will actually evaluate + the validity or otherwise of the password presented in an authentication request + object. +
+
+ + Configuration + + Aside from adding DaoAuthenticationProvider to your ProviderManager list (as discussed + at the start of this part of the reference guide), and ensuring a suitable + authentication mechanism is configured to present a UsernamePasswordAuthenticationToken, + the configuration of the provider itself is rather simple: + + @@ -38,38 +36,33 @@ ]]> - - - The PasswordEncoder and - SaltSource are optional. A - PasswordEncoder provides encoding and decoding of - passwords presented in the UserDetails object that - is returned from the configured UserDetailsService. - A SaltSource enables the passwords to be populated - with a "salt", which enhances the security of the passwords in the - authentication repository. PasswordEncoder - implementations are provided with Spring Security covering MD5, SHA - and cleartext encodings. Two SaltSource - implementations are also provided: - SystemWideSaltSource which encodes all passwords - with the same salt, and ReflectionSaltSource, which - inspects a given property of the returned - UserDetails object to obtain the salt. Please refer - to the JavaDocs for further details on these optional features. - - In addition to the properties above, the - DaoAuthenticationProvider supports optional caching - of UserDetails objects. The - UserCache interface enables the - DaoAuthenticationProvider to place a - UserDetails object into the cache, and retrieve it - from the cache upon subsequent authentication attempts for the same - username. By default the DaoAuthenticationProvider - uses the NullUserCache, which performs no caching. - A usable caching implementation is also provided, - EhCacheBasedUserCache, which is configured as - follows: - + + The PasswordEncoder and SaltSource are optional. + A PasswordEncoder provides encoding and decoding of passwords + presented in the UserDetails object that is returned from + the configured UserDetailsService. A + SaltSource enables the passwords to be populated with a "salt", + which enhances the security of the passwords in the authentication repository. + PasswordEncoder implementations are provided with Spring Security + covering MD5, SHA and cleartext encodings. Two SaltSource + implementations are also provided: SystemWideSaltSource which encodes + all passwords with the same salt, and ReflectionSaltSource, which + inspects a given property of the returned UserDetails + object to obtain the salt. Please refer to the JavaDocs for further details on these + optional features. + In addition to the properties above, the DaoAuthenticationProvider + supports optional caching of UserDetails objects. The + UserCache interface enables the + DaoAuthenticationProvider to place a + UserDetails object into the cache, and retrieve it + from the cache upon subsequent authentication attempts for the same username. By default + the DaoAuthenticationProvider uses the + NullUserCache, which performs no caching. A usable caching + implementation is also provided, EhCacheBasedUserCache, which is + configured as follows: + + @@ -89,42 +82,19 @@ class="org.springframework.security.core.userdetails.cache.EhCacheBasedUserCache"> ]]> - - - All Spring Security EH-CACHE implementations (including - EhCacheBasedUserCache) require an EH-CACHE - Cache object. The Cache object - can be obtained from wherever you like, although we recommend you use - Spring's factory classes as shown in the above configuration. If using - Spring's factory classes, please refer to the Spring documentation for - further details on how to optimise the cache storage location, memory - usage, eviction policies, timeouts etc. - In the majority of cases, where your application is a stateful web - application, you don't need to use a cache as the user's authentication - information will be stored in the HttpSession. - - - A design decision was made not to support account locking in the - DaoAuthenticationProvider, as doing so would have - increased the complexity of the UserDetailsService - interface. For instance, a method would be required to increase the - count of unsuccessful authentication attempts. Such functionality - could be easily provided by leveraging the application event - publishing features discussed below. - - DaoAuthenticationProvider returns an - Authentication object which in turn has its - principal property set. The principal will be - either a String (which is essentially the username) - or a UserDetails object (which was looked up from - the UserDetailsService). By default the - UserDetails is returned, as this enables - applications to add extra properties potentially of use in - applications, such as the user's full name, email address etc. If - using container adapters, or if your applications were written to - operate with Strings (as was the case for releases - prior to Spring Security 0.6), you should set the - DaoAuthenticationProvider.forcePrincipalAsString - property to true in your application context -
- \ No newline at end of file + + + All Spring Security EH-CACHE implementations (including + EhCacheBasedUserCache) require an EH-CACHE + Cache object. The Cache object can be obtained + from wherever you like, although we recommend you use Spring's factory classes as shown + in the above configuration. If using Spring's factory classes, please refer to the + Spring documentation for further details on how to optimise the cache storage location, + memory usage, eviction policies, timeouts etc. + + In the majority of cases, where your application is a stateful web application, + you don't need to use a cache as the user's authentication information will be + stored in the HttpSession. + +
+ diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index e74553a473..5f3df4da0b 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -113,7 +113,7 @@
<literal>web.xml</literal> Configuration The first thing you need to do is add the following filter declaration to your - web.xml file: web.xml file: springSecurityFilterChain org.springframework.web.filter.DelegatingFilterProxy @@ -277,7 +277,7 @@ containing the standard Spring Security user data tables. Alternatively, you could configure a Spring Security JdbcDaoImpl bean and point at that using the - user-service-ref attribute: user-service-ref attribute: Adding HTTP/HTTPS Channel Security If your application supports both HTTP and HTTPS, and you require that particular URLs can only be accessed over HTTPS, then this is directly supported using the - requires-channel attribute on <intercept-url>: requires-channel attribute on <intercept-url>: @@ -406,14 +406,21 @@ version of a standard namespace filter, such as the UsernamePasswordAuthenticationProcessingFilter which is created by the <form-login> element, taking advantage of some of the extra - configuration options which are available by using defining the bean directly. How can you - do this with namespace configuration, since the filter chain is not directly exposed? - The order of the filters is always strictly enforced when using the namespace. Each - Spring Security filter implements the Spring Ordered - interface and the filters created by the namespace are sorted during initialization. The - standard Spring Security filters each have an alias in the namespace. The filters, aliases - and namespace elements/attributes which create the filters are shown in . + configuration options which are available by using the bean explicitly. How can you do this + with namespace configuration, since the filter chain is not directly exposed? + The order of the filters is always strictly enforced when using the namespace. When the + application context is being created, the filter beans are sorted by the namespace handling + code and the standard Spring Security filters each have an alias in the namespace and a + well-known position. + In previous versions, the sorting took place after the filter instances had been + created, during post-processing of the application context. In version 3.0+ the sorting + is now done at the bean metadata level, before the classes have been instantiated. This + has implications for how you add your own filters to the stack as the entire filter list + must be known during the parsing of the <http> element, so the + syntax has changed slightly in 3.0. + The filters, aliases and namespace elements/attributes which create the filters are + shown in . The filters are listed in the order in which they + occur in the filter chain.
Standard Filter Aliases and Ordering @@ -510,10 +517,13 @@
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: - - - ]]> You can also use the after or before + + + + + + ]]> + You can also use the after or before attributes if you want your filter to be inserted before or after another filter in the stack. The names "FIRST" and "LAST" can be used with the position attribute to indicate that you want your filter to appear before or after the entire stack, @@ -575,12 +585,12 @@
Method Security - From version 2.0 onwards Spring Security has improved support substantially for adding security to your - service layer methods. It provides support for JSR-250 security - as well as the framework's native @Secured - annotation. You can apply security to a single bean, using the - intercept-methods element to decorate the bean declaration, or you can - secure multiple beans across the entire service layer using the AspectJ style pointcuts. + From version 2.0 onwards Spring Security has improved support substantially for adding + security to your service layer methods. It provides support for JSR-250 security as well as + the framework's native @Secured annotation. You can apply security to a + single bean, using the intercept-methods element to decorate the bean + declaration, or you can secure multiple beans across the entire service layer using the + AspectJ style pointcuts.
The <literal><global-method-security></literal> Element This element is used to enable annotation-based security in your application (by @@ -664,7 +674,7 @@ For method security, you do this by setting the access-decision-manager-ref attribute on global-method-securityto the Id of the appropriate - AccessDecisionManager bean in the application context: AccessDecisionManager bean in the application context: ... @@ -681,8 +691,9 @@ We've touched on the idea that the namespace configuration automatically registers an authentication manager bean for you. This is an instance of Spring Security's ProviderManager class, which you may already be familiar with if - you've used the framework before. If not, it will be covered later, in . - You can't use a custom AuthenticationManager if you are using either HTTP or method security + you've used the framework before. If not, it will be covered later, in . You can't use a custom + AuthenticationManager if you are using either HTTP or method security through the namespace, but this should not be a problem as you have full control over the AuthenticationProviders that are used. You may want to register additional AuthenticationProvider beans diff --git a/docs/manual/src/docbook/springsecurity.xml b/docs/manual/src/docbook/springsecurity.xml index d4f1ce85e9..0282d24322 100644 --- a/docs/manual/src/docbook/springsecurity.xml +++ b/docs/manual/src/docbook/springsecurity.xml @@ -115,7 +115,9 @@ + + Authorization @@ -164,7 +165,7 @@ Essentially standalone features which do not have to follow on directly from earlier chapters --> - In this part we cover some of the more advanced features of the framework. + In this part we cover some of the more advanced and less-commonly used features of the framework. @@ -172,6 +173,7 @@ + diff --git a/docs/manual/src/docbook/technical-overview.xml b/docs/manual/src/docbook/technical-overview.xml index e3f393cbe8..d45d4fb3f6 100644 --- a/docs/manual/src/docbook/technical-overview.xml +++ b/docs/manual/src/docbook/technical-overview.xml @@ -28,8 +28,8 @@ web-application security, LDAP or namespace configuration. We'll take a look here at some of the Java types that you'll find in the core module. They represent the building blocks of the the framework, so if you ever need to go beyond a simple namespace configuration then it's - important that you understand what they are, even if you don't actually need to directly - interact with them. + important that you understand what they are, even if you don't actually need to interact with + them directly.
SecurityContextHolder, SecurityContext and Authentication Objects The most fundamental object is SecurityContextHolder. This is @@ -44,13 +44,15 @@ no need to worry about it. Some applications aren't entirely suitable for using a ThreadLocal, because of the specific way they work with threads. For example, a Swing client might want - all threads in a Java Virtual Machine to use the same security context. For this situation - you would use the SecurityContextHolder.MODE_GLOBAL. Other applications - might want to have threads spawned by the secure thread also assume the same security - identity. This is achieved by using + all threads in a Java Virtual Machine to use the same security context. + SecurityContextHolder can be configured with a strategy on startup + to specify how you would like the contex to be stored. For a standalone application you + would use the SecurityContextHolder.MODE_GLOBAL strategy. Other + applications might want to have threads spawned by the secure thread also assume the same + security identity. This is achieved by using SecurityContextHolder.MODE_INHERITABLETHREADLOCAL. You can change the mode from the default SecurityContextHolder.MODE_THREADLOCAL in two ways. - The first is to set a system property. Alternatively, call a static method on + The first is to set a system property, the second is to call a static method on SecurityContextHolder. Most applications won't need to change from the default, but if you do, take a look at the JavaDocs for SecurityContextHolder to learn more. @@ -74,9 +76,9 @@ if (principal instanceof UserDetails) { } The object returned by the call to getContext() is an instance of the SecurityContext interface. This is the - object that is kept in thread-local storage. Most authentication mechanisms withing Spring - Security return an instance of UserDetails as the principal - as we'll see below. + object that is kept in thread-local storage. As we'll see below, Most authentication + mechanisms withing Spring Security return an instance of + UserDetails as the principal.
@@ -109,15 +111,15 @@ if (principal instanceof UserDetails) { On successful authentication, UserDetails is used to build the Authentication object that is stored in the SecurityContextHolder (more on this below). The good news is that we provide a - number of UserDetailsService implementations, including one - that uses an in-memory map (InMemoryDaoImpl) and another that uses - JDBC (JdbcDaoImpl). Most users tend to write their own, - though, with their implementations often simply sitting on top of an existing Data Access - Object (DAO) that represents their employees, customers, or other users of the application. - Remember the advantage that whatever your UserDetailsService - returns can always be obtained from the SecurityContextHolder using - the above code fragment. + xlink:href="#tech-intro-authentication-mgr">below). The good news is that we + provide a number of UserDetailsService implementations, + including one that uses an in-memory map (InMemoryDaoImpl) and + another that uses JDBC (JdbcDaoImpl). Most users tend to + write their own, though, with their implementations often simply sitting on top of an + existing Data Access Object (DAO) that represents their employees, customers, or other users + of the application. Remember the advantage that whatever your + UserDetailsService returns can always be obtained from the + SecurityContextHolder using the above code fragment.
GrantedAuthority @@ -321,10 +323,8 @@ Successfully authenticated. Security context contains: \ (or equivalent) that reads the third-party user information from a location, build a Spring Security-specific Authentication object, and put it onto the SecurityContextHolder. - - If you're wondering how the AuthenticationManager - manager is implemented in a real world example, we'll look at that in - + If you're wondering how the AuthenticationManager + manager is implemented in a real world example, we'll look at that in
@@ -511,10 +511,11 @@ Successfully authenticated. Security context contains: \ What are Configuration Attributes? A configuration attribute can be thought of as a String that has special meaning to the classes used by AbstractSecurityInterceptor. - They are represented by the interface ConfigAttribute within - the framework. They may be simple role names or have more complex meaning, depending on the how - sophisticated the AccessDecisionManager implementation is. - The AbstractSecurityInterceptor is configured with a + They are represented by the interface ConfigAttribute + within the framework. They may be simple role names or have more complex meaning, + depending on the how sophisticated the + AccessDecisionManager implementation is. The + AbstractSecurityInterceptor is configured with a SecurityMetadataSource which it uses to look up the attributes for a secure object. Usually this configuration will be hidden from the user. Configuration attributes will be entered as annotations on secured methods, or as access