diff --git a/docs/manual/src/docbook/concurrent-sessions.xml b/docs/manual/src/docbook/concurrent-sessions.xml index e67b61e7ac..cd9ef4fa2c 100644 --- a/docs/manual/src/docbook/concurrent-sessions.xml +++ b/docs/manual/src/docbook/concurrent-sessions.xml @@ -1,14 +1,31 @@ - + - Concurrent Session Handling + Session Management +
+ SessionManagementFilter + HTTP session related functonality is handled by the + SessionManagementFilter. This +
+
+ Concurrency Control Spring Security is able to prevent a principal from concurrently authenticating to the same application more than a specified number of times. Many ISVs take advantage of this to enforce licensing, whilst network administrators like this feature because it helps prevent people from sharing login names. You can, for example, stop user "Batman" from logging onto the web application from two different sessions. + This feature is supported by the namespace, so please check the earlier namespace chapter + for the simplest configuration. Sometimes you need to customize things though. + The implementation has changed substantially in Spring Security 3. Previously the + concurrent authentication check was made by the ProviderManager, which + could be injected with a ConcurrentSessionController which would check if + the user was attempting to exceed the number of sessions permitted. However, this approach + required that an HTTP session be created in advance, which is undesirable. In Spring Security + 3, the user is first authenticated by the AuthenticationManager + and once they are successfully authenticated, a session is created and the check is made + whether they are allowed to have another session open. To use concurrent session support, you'll need to add the following to web.xml: @@ -51,4 +68,5 @@ ]]> +
diff --git a/docs/manual/src/docbook/namespace-config.xml b/docs/manual/src/docbook/namespace-config.xml index f843e81b7f..d2f5645928 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 be set on 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 be set on 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 these work together in the following sections. @@ -177,9 +161,10 @@ application (which will be used for access control). It is also possible to load user information from a standard properties file using the properties attribute on user-service. See the section on in-memory authentication for more details. Using - the <authentication-provider> element means that the user - information will be used by the authentication manager to process authentication requests. + xlink:href="#core-services-in-memory-service">in-memory authentication for more + details. Using the <authentication-provider> element means that the + user information will be used by the authentication manager to process authentication + requests. At this point you should be able to start up your application and you will be required to log in to proceed. Try it out, or try experimenting with the "tutorial" sample application that comes with the project. The above configuration actually adds quite a few @@ -196,15 +181,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 inluded 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 was made part - of the default <http> configuration, so the - <anonymous /> element is effectively added regardless of - whether auto-config is enabled. - . They each have attributes which can be used to alter their behaviour. - + basic authentication and logout handling services respectively In versions + prior to 3.0, this list also inluded 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 was made part of the default + <http> configuration, so the <anonymous + /> element is effectively 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 @@ -366,11 +350,13 @@ ]]> - + + +
- Concurrent Session Control + Session Management If you wish to place constraints on a single user's ability to log in to your application, Spring Security supports this out of the box with the following simple additions. First you need to add the following listener to your web.xml @@ -381,21 +367,30 @@ org.springframework.security.web.session.HttpSessionEventPublisher -]]> Then add the following line to your application context: Then add the following lines to your application context: ... - + + + ]]> This will prevent a user from logging in multiple times - a second login will cause the first to be invalidated. Often you would prefer to prevent a second login, in which case you can use ... - + + + ]]> - The second login will then be rejected. - - + The second login will then be rejected. By + rejected, we mean that the user will be sent to the + authentication-failure-url if form-based login is being used. If the + second authentication takes place through another non-interactive mechanism, such as + remember-me, an unauthorized (402) error will be sent to the + client. If instead you want to use an error page, you can add the attribute + error-url to the concurrency-control + element.
OpenID Login @@ -427,112 +422,50 @@ 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 - - - CONCURRENT_SESSION_FILTER - ConcurrentSessionFilter - - http/concurrent-session-control - - - SESSION_CONTEXT_INTEGRATION_FILTER - HttpSessionContextIntegrationFilter - http - - - LOGOUT_FILTER - LogoutFilter - http/logout - - - X509_FILTER - X509PreAuthenticatedProcessigFilter - http/x509 - - - PRE_AUTH_FILTER - AstractPreAuthenticatedProcessingFilter Subclasses - N/A - - - CAS_PROCESSING_FILTER - CasProcessingFilter - N/A - - - AUTHENTICATION_PROCESSING_FILTER - UsernamePasswordAuthenticationProcessingFilter - http/form-login - - - BASIC_PROCESSING_FILTER - BasicProcessingFilter - http/http-basic - - - SERVLET_API_SUPPORT_FILTER - SecurityContextHolderAwareRequestFilter - http/@servlet-api-provision - - - REMEMBER_ME_FILTER - RememberMeProcessingFilter - http/remember-me - - - ANONYMOUS_FILTER - AnonymousProcessingFilter - http/anonymous - - - EXCEPTION_TRANSLATION_FILTER - ExceptionTranslationFilter - http - - - NTLM_FILTER - NtlmProcessingFilter - N/A - - - FILTER_SECURITY_INTERCEPTOR - FilterSecurityInterceptor - http - - - SWITCH_USER_FILTER - SwitchUserProcessingFilter - 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 + CONCURRENT_SESSION_FILTERConcurrentSessionFilter + http/concurrent-session-control + SESSION_CONTEXT_INTEGRATION_FILTERHttpSessionContextIntegrationFilterhttp + LOGOUT_FILTER + LogoutFilterhttp/logout + X509_FILTER + X509PreAuthenticatedProcessigFilterhttp/x509 + PRE_AUTH_FILTER + AstractPreAuthenticatedProcessingFilter + SubclassesN/A CAS_PROCESSING_FILTER + CasProcessingFilterN/A + AUTHENTICATION_PROCESSING_FILTER + UsernamePasswordAuthenticationProcessingFilterhttp/form-login + BASIC_PROCESSING_FILTER + BasicProcessingFilterhttp/http-basic + SERVLET_API_SUPPORT_FILTERSecurityContextHolderAwareRequestFilterhttp/@servlet-api-provision + REMEMBER_ME_FILTER + RememberMeProcessingFilterhttp/remember-me + ANONYMOUS_FILTER + AnonymousProcessingFilterhttp/anonymous + EXCEPTION_TRANSLATION_FILTER + ExceptionTranslationFilterhttp + NTLM_FILTER + NtlmProcessingFilterN/A + FILTER_SECURITY_INTERCEPTOR + FilterSecurityInterceptorhttp + SWITCH_USER_FILTER + SwitchUserProcessingFilterN/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: @@ -583,20 +516,14 @@ Security protects against this automatically by creating a new session when a user 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 - <http>, 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. - - + <http>, 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.