From 88caa4d221ee75c64704c3274fe46e9545294a4e Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Mon, 14 Dec 2009 15:13:57 +0000 Subject: [PATCH] SEC-1322: More doc updates following further user requests for clarification --- .../manual/src/docbook/anon-auth-provider.xml | 30 +- .../src/docbook/authorization-common.xml | 23 +- docs/manual/src/docbook/namespace-config.xml | 272 ++++++------------ docs/manual/src/resources/css/manual.css | 10 + 4 files changed, 131 insertions(+), 204 deletions(-) diff --git a/docs/manual/src/docbook/anon-auth-provider.xml b/docs/manual/src/docbook/anon-auth-provider.xml index 190322a4b5..d36f75212f 100644 --- a/docs/manual/src/docbook/anon-auth-provider.xml +++ b/docs/manual/src/docbook/anon-auth-provider.xml @@ -1,4 +1,5 @@ - + Anonymous Authentication @@ -69,10 +70,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 @@ -83,8 +84,8 @@ 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. @@ -126,11 +127,16 @@ 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 the authorization - chapter. It uses an + interceptor configuration replaced with IS_AUTHENTICATED_ANONYMOUSLY, + which is effectively the same thing when defining access controls. This is an example of + the use of the AuthenticatedVoter which we will see in the authorization chapter. It uses an AuthenticationTrustResolver to process this - particular configuration attribute and grant access to aonymous users. + particular configuration attribute and grant access to aonymous users. The + AuthenticatedVoter approach is more powerful, since it allows + you to differentiate between anonymous, remember-me and fully-authenticated users. If + you don't need this functionality though, then you can stick with + ROLE_ANONYMOUS, which will be processed by Spring Security's + standard RoleVoter. diff --git a/docs/manual/src/docbook/authorization-common.xml b/docs/manual/src/docbook/authorization-common.xml index 1f1fbb7c8c..db6f10c622 100644 --- a/docs/manual/src/docbook/authorization-common.xml +++ b/docs/manual/src/docbook/authorization-common.xml @@ -100,7 +100,7 @@ --> + format="GIF"/> @@ -160,10 +160,13 @@ boolean supports(Class clazz); <classname>AuthenticatedVoter</classname> Another voter which we've implicitly seen is the AuthenticatedVoter, which can be used to differentiate between - anonymous, fully-authenticated and remember-me authenticated users. When we've used the - attribute IS_AUTHENTICATED_ANONYMOUSLY to grant anonymous access, this - attribute was being processed by the AuthenticatedVoter. See the - Javadoc for this class for more information. + anonymous, fully-authenticated and remember-me authenticated users. Many sites allow + certain limited access under remember-me authentication, but require a user to confirm + their identity by logging in for full access. + When we've used the attribute IS_AUTHENTICATED_ANONYMOUSLY to grant + anonymous access, this attribute was being processed by the + AuthenticatedVoter. See the Javadoc for this class for more + information.
Custom Voters @@ -197,15 +200,11 @@ boolean supports(Class clazz); that integrate with its ACL capabilities. illustrates Spring Security's AfterInvocationManager and its concrete implementations.
- After Invocation Implementation - - + xml:id="authz-after-invocation">After Invocation + Implementation - - -
+ Like many other parts of Spring Security, AfterInvocationManager has a single concrete implementation, AfterInvocationProviderManager, which polls a list of AfterInvocationProviders. Each diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index 175f5f3943..fbba3ba380 100644 --- a/docs/manual/src/docbook/namespace-config.xml +++ b/docs/manual/src/docbook/namespace-config.xml @@ -21,13 +21,13 @@ ]]> This is much simpler than wiring up the equivalent Apache Directory Server beans. The most common alternative configuration requirements are supported by attributes on the ldap-server element and the user is isolated from worrying about which - beans they need to create and what the bean property names are. - You can find out more about the use of the ldap-server element in - the chapter on LDAP. - . Use of a good XML editor while editing the application context file should - provide information on the attributes and elements that are available. We would recommend that - you try out the SpringSource Tool - Suite as it has special features for working with standard Spring namespaces. + beans they need to create and what the bean property names are. You can find + out more about the use of the ldap-server element in the chapter on + LDAP.. Use of a good XML editor while + editing the application context file should provide information on the attributes and elements + that are available. We would recommend that you try out the SpringSource Tool Suite as it + has special features for working with standard Spring namespaces. To start using the security namespace in your application context, all you need to do is add the schema declaration to your application context file: The namespace is designed to capture the most common uses of the framework and provide a simplified and concise syntax for enabling them within an application. The design is based around the large-scale dependencies within the framework, and can be divided up into the - following areas: - - + following areas: Web/HTTP Security - the most complex part. Sets up the filters and related service beans used to apply the framework authentication mechanisms, to - secure URLs, render login and error pages and much more. - - - + secure URLs, render login and error pages and much + more. Business Object (Method) Security - options for securing the - service layer. - - - + service layer. AuthenticationManager - handles authentication requests from - other parts of the framework. - - - + other parts of the framework. AccessDecisionManager - provides access decisions for web and method security. A default one will be registered, but you can also choose to use a - custom one, declared using normal Spring bean syntax. - - - + custom one, declared using normal Spring bean + syntax. AuthenticationProviders - mechanisms against which the authentication manager authenticates users. The namespace provides supports for several standard options and also a means of adding custom beans declared using a - traditional syntax. - - - + traditional syntax. UserDetailsService - closely related to authentication providers, - but often also required by other beans. - + but often also required by other beans. We'll see how to configure these in the following sections. @@ -148,20 +132,20 @@ requirements for requests matching the given pattern. With the default configuration, this is typically a comma-separated list of roles, one of which a user must have to be allowed to make the request. Access-control in Spring Security is not limited to the use of simple - roles, however, and we'll see later how the interpretation can vary - The interpretation of the comma-separated values in the access - attribute depends on the implementation of the The + interpretation of the comma-separated values in the access attribute + depends on the implementation of the AccessDecisionManager which is used. In Spring Security 3.0, the attribute can - also be populated with an EL expression. - . + also be populated with an EL + expression.. You can use multiple <intercept-url> elements to define different access requirements for different sets of URLs, but they will be evaluated in the order listed and the first match will be used. So you must put the most specific matches at the top. You can also add a method attribute to limit the match to a particular HTTP method (GET, POST, - PUT etc.). For a pattern defined both with and without a method, the - method-specific match will take precedence regardless of ordering. + PUT etc.). If a request matches multiple patterns, the + method-specific match will take precedence regardless of ordering. To add some users, you can define a set of test data directly in the namespace: @@ -184,8 +168,8 @@ DaoAuthenticationProvider bean and the <user-service> element creates an InMemoryDaoImpl. All authentication-provider - elements must be within the authentication-manager element, which - creates a ProviderManager and registers the authentication + elements must be children of the <authentication-manager> element, + which creates a ProviderManager and registers the authentication providers with it. You can find more detailed information on the beans that are created in the namespace appendix. It's worth cross-checking this if you want to start understanding what the important classes in the @@ -217,15 +201,14 @@ ]]> These other elements are responsible for setting up form-login, basic - 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 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 their behaviour. - + 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 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 + their behaviour.
Form and Basic Login Options @@ -246,16 +229,15 @@ Note that you can still use auto-config. The form-login element just overrides the default settings. Also note that we've added an extra intercept-url element to say that any - requests for the login page should be available to anonymous users - See the chapter on anonymous authentication - and also the AuthenticatedVoter - class for more details on how the value - IS_AUTHENTICATED_ANONYMOUSLY is processed. - . Otherwise the request would be matched by the pattern /** - and it wouldn't be possible to access the login page itself! This is a common - configuration error and will result in an infinite loop in the application. Spring - Security will emit a warning in the log if your login page appears to be secured. It is - also possible to have all requests matching a particular pattern bypass the security + requests for the login page should be available to anonymous users See the + chapter on anonymous authentication and also the + AuthenticatedVoter class for + more details on how the value IS_AUTHENTICATED_ANONYMOUSLY is + processed.. Otherwise the request would be matched by the pattern + /** and it wouldn't be possible to access the login page itself! This + is a common configuration error and will result in an infinite loop in the application. + Spring Security will emit a warning in the log if your login page appears to be secured. + It is also possible to have all requests matching a particular pattern bypass the security filter chain completely: @@ -476,20 +458,14 @@ logs in. If you don't require this protection, or it conflicts with some other requirement, you can control the behaviour using the session-fixation-protection attribute on - <session-management>, which has three options - - migrateSession - creates a new session and copies the - existing session attributes to the new session. This is the default. - - - none - Don't do anything. The original session will be - retained. - - - newSession - Create a new "clean" session, without copying - the existing session data. - - + <session-management>, which has three options + migrateSession - creates a new + session and copies the existing session attributes to the new session. This is the + default.none - Don't do + anything. The original session will be + retained.newSession - Create + a new "clean" session, without copying the existing session + data.
@@ -526,112 +502,48 @@ 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 - - - - Alias - Filter Class - Namespace Element or Attribute - - - - - CHANNEL_FILTER - ChannelProcessingFilter - http/intercept-url@requires-channel - - - CONCURRENT_SESSION_FILTER - ConcurrentSessionFilter - - session-management/concurrency-control - - - SECURITY_CONTEXT_FILTER - SecurityContextPersistenceFilter - http - - - LOGOUT_FILTER - LogoutFilter - http/logout - - - X509_FILTER - X509AuthenticationFilter - http/x509 - - - PRE_AUTH_FILTER - AstractPreAuthenticatedProcessingFilter Subclasses - N/A - - - CAS_FILTER - CasAuthenticationFilter - N/A - - - FORM_LOGIN_FILTER - UsernamePasswordAuthenticationFilter - http/form-login - - - BASIC_AUTH_FILTER - BasicAuthenticationFilter - http/http-basic - - - SERVLET_API_SUPPORT_FILTER - SecurityContextHolderAwareFilter - http/@servlet-api-provision - - - REMEMBER_ME_FILTER - RememberMeAuthenticationFilter - http/remember-me - - - ANONYMOUS_FILTER - AnonymousAuthenticationFilter - http/anonymous - - - SESSION_MANAGEMENT_FILTER - SessionManagementFilter - session-management - - - EXCEPTION_TRANSLATION_FILTER - ExceptionTranslationFilter - http - - - FILTER_SECURITY_INTERCEPTOR - FilterSecurityInterceptor - http - - - SWITCH_USER_FILTER - SwitchUserFilter - N/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: 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 OrderingAliasFilter ClassNamespace Element or + Attribute + CHANNEL_FILTERChannelProcessingFilterhttp/intercept-url@requires-channel + CONCURRENT_SESSION_FILTERConcurrentSessionFilter + session-management/concurrency-control + SECURITY_CONTEXT_FILTERSecurityContextPersistenceFilterhttp + LOGOUT_FILTER + LogoutFilterhttp/logout + X509_FILTER + X509AuthenticationFilterhttp/x509 + PRE_AUTH_FILTER + AstractPreAuthenticatedProcessingFilter + SubclassesN/A CAS_FILTER + CasAuthenticationFilterN/A + FORM_LOGIN_FILTER + UsernamePasswordAuthenticationFilterhttp/form-login + BASIC_AUTH_FILTER + BasicAuthenticationFilterhttp/http-basic + SERVLET_API_SUPPORT_FILTERSecurityContextHolderAwareFilterhttp/@servlet-api-provision + REMEMBER_ME_FILTER + RememberMeAuthenticationFilterhttp/remember-me + ANONYMOUS_FILTER + AnonymousAuthenticationFilterhttp/anonymous + SESSION_MANAGEMENT_FILTERSessionManagementFiltersession-managementEXCEPTION_TRANSLATION_FILTER + ExceptionTranslationFilterhttp + FILTER_SECURITY_INTERCEPTOR + FilterSecurityInterceptorhttp + SWITCH_USER_FILTER + 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/resources/css/manual.css b/docs/manual/src/resources/css/manual.css index 4314f6b328..524d462211 100644 --- a/docs/manual/src/resources/css/manual.css +++ b/docs/manual/src/resources/css/manual.css @@ -57,3 +57,13 @@ div.table td { padding-left: 7px; padding-right: 7px; } + +.sidebar { + float: right; + margin: 10px 0 10px 30px; + padding: 10px 20px 20px 20px; + width: 33%; + border: 1px solid black; + background-color: #F4F4F4; + font-size: 14px; +}