namespace document.

src/site/apt/namespaces.apt

@@ -0,0 +1,159 @@
+                                ----------------------------------------
+                                     Security Namespace Configuration
+                                ----------------------------------------
+                                         ------------------------
+                                           (2007-11-7 draft)
+                                         ------------------------
+
+
+Overview
+
+
+* Summary
+
+    Spring Security will make use of Spring 2.0 namespace-based configuration features to allow much more concise
+    configuration. This document outlines the current state of development and the features that have been
+    implemented so far and raises points for discussion. The features are still largely experimental and subject to
+    change.
+
+    The {{{http://acegisecurity.svn.sourceforge.net/svnroot/acegisecurity/spring-security/trunk/core/src/main/resources/org/springframework/security/config/}schema files}}
+    can be found in the core package.
+
+    For simplicity, a relax NG compact schema (the rnc file) has been used as it is easier to work with.
+    This is then coverted into a W3C schema using trang.
+
+* Design
+
+    The initial aim is to provide a relatively small set of namespace configuration options which capture the most
+    common uses of framework, especially for inexperienced users who don't require much in the way of customization.
+    The focus should be mainly on providing high-level components which logically match the different aspects of
+    securing an application. While it is also useful to have namespace options for simplifying the configuration of
+    existing framework beans, this is a somewhat orthogonal requirement, with different target users, and will be dealt
+    with separately. Only the most obvious customizations will be implemented to start with.
+
+    With these aims in mind, the design is largely based around the large-scale dependencies within the framework.
+    It can be divided up into the following areas:
+
+    * <<Web/HTTP Security>> - this is by far the largest and most complex area, consisting of
+
+        * Filter chain proxy
+
+        * HttpSessionContextIntegrationFilter - special filter which is of key importance.
+
+        * The filters which are responsible for most of Spring Security's web application features.
+
+        * ExceptionTranslationFilter and FilterSecurityInterceptor - other special filters.
+
+        * Authentication entry point(s).
+
+        * Concurrent session support (optional).
+
+        * Remember-me service (optional).
+
+    The only inward dependency here is that the AuthenticationManager must be made aware of the
+    ConcurrentSessionController (if configured). Apart from this, the other areas of the framework are unaware of
+    web-related functionality.
+
+    * <<Business Object (Method) Security>> - This is currently implemented using a bean decorator within the
+     business object bean, which is a relatively simple syntax.
+
+    * <<AuthenticationManager>> - this is the main dependency of other parts of the framework. The namespace
+    configuration creates an instance of ProviderManager as required and registers it under a known name. It assumes
+    that this will be used by all the configured beans. This currently happens automatically. It might be worth
+    introducing a
+
+---
+    <security:authentication-manager id="othername"/>
+---
+
+    element just to allow users to explicitly configure an authentication manager which they can use in other beans.
+    The additional name could be registered as an alias.
+
+    * <<AccessDecisionManager>> - The security interceptors (both for method and http security) require access to
+    an access decision manager. At the moment a default one is created and used by both, but they should additionally
+    support the use of an independently configured access manager, based on Id. The standard bean syntax should be
+    sufficient for the moment.
+
+    * <<AuthenticationProviders>> - these can be created individually and register themselves with the authentication
+    manager. Current namespace options are limited but each provider should be pretty much self-contained and hence
+    relatively simple to implement. There may be multiple providers within an application so some means of ordering will
+    be required.
+
+    * <<UserDetailsService>> - Closely related to the authentication providers, but often also required by other beans.
+    Again the implementations should be relatively straightforward. There may be multiple implementations within the
+    application.
+
+
+* Http Security
+
+   Probably the best starting point here is to look at the namespace configuration which is currently in use in the
+   sample application:
+
++--------------------------------------------------------------------------------------------------------------------
+
+<beans xmlns="http://www.springframework.org/schema/beans"
+    xmlns:security="http://www.springframework.org/schema/security"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
+http://www.springframework.org/schema/security http://www.springframework.org/schema/security/spring-security-2.0.xsd">
+
+    <security:http>
+        <security:intercept-url pattern="/secure/extreme/**" access="ROLE_SUPERVISOR"/>
+        <security:intercept-url pattern="/secure/**" access="IS_AUTHENTICATED_REMEMBERED" />
+        <security:intercept-url pattern="/**" access="IS_AUTHENTICATED_ANONYMOUSLY" />
+
+        <security:form-login />
+        <security:http-basic realm="SpringSecurityTutorialApp"  />
+        <security:logout />
+        <security:concurrent-session-control maxSessions="1" exceptionIfMaximumExceeded="true"/>
+
+        <security:remember-me key="doesntmatter" tokenRepository="tokenRepo"/>
+    </security:http>
+
+    <bean name="tokenRepo" class="org.springframework.security.ui.rememberme.InMemoryTokenRepositoryImpl"/>
+
+    <security:authentication-provider>
+        <security:user-service>
+            <security:user name="bob" password="bobspassword" authorities="ROLE_SUPERVISOR" />
+            <security:user name="bill" password="billspassword" authorities="ROLE_A,ROLE_B" />
+        </security:user-service>
+    </security:authentication-provider>
+
+</beans>
+
++--------------------------------------------------------------------------------------------------------------------
+
+** \<security:http /\>
+
+    This element groups the other http-specific elements together and has attributes which allow the
+    session creation strategy to be set. It also allows you to specify the type of pattern that will be used for URL
+    definitions within the block. This defaults to ``ant'' since this is what users almost always use in practice.
+
+    The {{{./spring-security-core/xref/org/springframework/security/config/HttpSecurityBeanDefinitionParser.html}HttpSecurityBeanDefinitionParser}}
+    class is responsible for handling the contents. It creates a FilterChainProxy
+    instance, HttpSessionContextIntegrationFilter, FilterSecurityInterceptor and ExceptionTranslationFilter and parses
+    the child intercept-url elements (see below). It then delegates to separate parsers to handle the contents of other
+    child elements. These encapsulate the functionality of separate web application concerns which are implemented
+    by Spring Security and will typically each create a filter and possibly one or more other beans.
+
+    Finally a post processor (HttpSecurityConfigPostProcessor) is registered to handle issues which can't be done
+    until the application context has been completed. This includes assembling and ordering the filter chain. The core
+    filters now implement Ordered and a standard ordering has been established for them. Other filters in the
+    context must also implement Ordered to be considered, so it may be necessary to provide an element which can be
+    used to decorate filter beans to achieve this, if the user can't (or doesn't want to) make their code implement
+    Ordered explicitly.
+
+
+** \<security:intercept-url /\>
+
+    In a traditional, bean-configured setup, there are several beans which require the use of URL patterns -
+    FilterChainProxy, FilterSecurityInterceptor and ChannelProcessingFilter. These can now be specified using a
+    single construct and the appropriate beans created and assembled by the parser. This allows options to be combined
+    in a more logical fashion without duplication. The user picks the important URLs for their application, defines the
+    patterns for them and then specifies which filters should be used, what access configuration attributes
+    the FilterSecurityInterceptor should enforce and if any channel restrictions apply. Only the access decision part
+    has been implemented. The only option for filters is currently "none", which will omit the URL from the security
+    filter chain entirely. It's not clear how or if additional filter order customization should be implemented (other
+    than by allowing Ids to be set on the various child elements). Channel security should be straightforward.
+
+