SEC-653: Started namespace configuration overview

src/docbkx/namespace-config.xml

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="namespace-config" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <info>
+    <title>Security Namespace Configuration</title>
+  </info>
+  <section>
+    <info>
+      <title>Introduction</title>
+    </info>
+    <para>
+      Namespace configuration is a feature of Spring 2.0 which allows a bean or beans to be
+      configured by parsing XML elements from a namespace which are included in your application
+      context file (in addition to elements from the tradtitional Spring "beans" namespace). You can
+      find more information in the Spring
+      <link xlink:href="http://static.springframework.org/spring/docs/2.5.x/reference/xsd-config.html">
+        Reference Documentation</link>. A namespace element be used simply to allow a more concise
+      way of configuring an existing bean or, more powerfully, to define an alternative
+      configuration syntax which more closely matches the problem domain and hides the underlying
+      complexity from the user. A relatively simple element may conceal the fact that many beans and
+      processing steps are being added to the application context. For example, adding the following
+      element from the securty namespace to an application context will start up an embedded LDAP
+      server for testing use within the application:
+      <programlisting><![CDATA[ 
+  <security:ldap-server id="embeddedLdapServer"/>
+]]></programlisting>
+      which is much simpler than wiring up the equivalent Apache Directory Server beans. The most
+      common alterative configuration requirements are supported by attributes on the
+      <literal>ldap-server</literal> element.
+      <footnote>
+        <para>You can find out more about the use of the
+          <literal>ldap-server</literal>
+          element in the chapter on
+          <link xlink:href="ldap">LDAP</link>.</para>
+      </footnote>. The user is isolated from worrying about which beans they need to be set
+      on and what the bean property names are. Use of a good XML editor while editing the
+      configuration file should provide information on the attributes and elements that are
+      available (and their purpose).
+    </para>
+    <para>
+      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:
+<programlisting>
+  <![CDATA[
+<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">  
+    ...
+</beans>
+  ]]></programlisting>
+      In many of the examples you will see (and in the sample) applications, we will often use "security" as the default
+      namespace rather than "beans", which means we can omit the prefix on all the security namespace elements,
+      making the context easier to read. You may also want to do this if you have your application context divided up
+      into separate files and have most of your security configuration in one of them. Your application context file would then
+      start like this
+      <programlisting><![CDATA[
+<beans:beans xmlns="http://www.springframework.org/schema/security"
+   xmlns:beans="http://www.springframework.org/schema/beans">
+    ...
+</beans:beans>
+]]></programlisting>
+    </para>
+  </section>
+  <section>
+    <info>
+      <title>Design</title>
+    </info>
+    <para>
+      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 largely based around the large-scale dependencies
+    within the framework, and can be divided up into the following areas:
+    <itemizedlist>
+      <listitem><para><emphasis>Web/HTTP Security</emphasis> - the most complex part. Sets up the filters and 
+        related service beans used to apply the framework authentication mechanisms, secure URLs, render login and error pages and much more.</para></listitem>
+      <listitem><para><emphasis>Business Object (Method) Security</emphasis> - options for securing the service layer.</para></listitem>
+      <listitem><para><emphasis>AuthenticationManager</emphasis> - handles authentication requests from other parts of the framework.</para></listitem>
+      <listitem><para><emphasis>AccessDecisionManager</emphasis> - provides access decisions for web and method security.</para></listitem>
+      <listitem><para><emphasis>AuthenticationProvider</emphasis>s - 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. </para></listitem>
+      <listitem><para><emphasis>UserDetailsService</emphasis> - closely related to authentication providers, but often also required by other beans.</para></listitem>
+      <!-- todo: diagram and link to other sections which describe the interfaces -->
+    </itemizedlist>    
+    </para>
+    
+  </section>
+</chapter>

src/docbkx/secured-objects.xml

@@ -1,7 +1,8 @@
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="secure-object-impls"><info><title>Secure Object Implementations</title></info>
-  
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="secure-object-impls">
+  <info><title>Secure Object Implementations</title></info>
 
-  <section xml:id="aop-alliance"><info><title>AOP Alliance (MethodInvocation) Security Interceptor</title></info>
+  <section xml:id="aop-alliance">
+    <info><title>AOP Alliance (MethodInvocation) Security Interceptor</title></info>
     
 
     <para>To secure <literal>MethodInvocation</literal>s, developers

src/docbkx/springsecurity.xml

@@ -9,7 +9,7 @@
         <subtitle>Reference Documentation</subtitle>
         
         <author>
-            <personname>Ben Alex</personname>
+            <personname>Ben Alex, Luke Taylor</personname>
         </author>
                 
         <releaseinfo>2.0-SNAPSHOT</releaseinfo>
@@ -80,6 +80,23 @@
     <para>Finally, welcome to the Spring Security <link xlink:href="#community" >community</link>.
     </para>
   </preface>
+  
+  <part xml:id="getting-started">
+    <title>Getting Started</title>
+    <partintro>
+    <para>The remaining parts of this guide provide an in-depth discussion of the
+      framework architecture and implementation classes, an understanding of which is important
+      if you need to do any serious customization. In this part, we take a slightly
+      gentler look at how to get started using some of the features of Spring Security 2.0.
+      The use of namespace configuration provides a much simpler path to securing
+      your application with little or no knowledge of the classes involved, unlike the traditional
+      Spring bean approach which required you to configure large numbers of beans.
+    </para>
+    </partintro>
+    
+    <xi:include href="namespace-config.xml" />
+
+  </part>
 
   <part xml:id="overall-architecture">
     <title>Overall Architecture</title>
@@ -93,15 +110,15 @@
       integration.</para>
     </partintro>
 
-    <xi:include href="introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="introduction.xml" />
     
-    <xi:include href="technical-overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="technical-overview.xml" />
 
-    <xi:include href="supporting-infrastructure.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="supporting-infrastructure.xml" />
     
-    <xi:include href="channel-security.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="channel-security.xml" />
     
-    <xi:include href="taglibs.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="taglibs.xml" />
   </part>
 
   <part xml:id="authentication">
@@ -117,21 +134,21 @@
 
     <xi:include href="common-auth-services.xml" />
 
-    <xi:include href="dao-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>    
+    <xi:include href="dao-auth-provider.xml" />    
 
-    <xi:include href="jaas-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="jaas-auth-provider.xml" />
 
-    <xi:include href="runas-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="runas-auth-provider.xml" />
     
-    <xi:include href="form-authentication.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="form-authentication.xml" />
     
-    <xi:include href="basic-authentication.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="basic-authentication.xml" />
     
-    <xi:include href="digest-authentication.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+    <xi:include href="digest-authentication.xml" />
     
-    <xi:include href="remember-me-authentication.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>    
+    <xi:include href="remember-me-authentication.xml" />    
     
-    <xi:include href="anon-auth-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>    
+    <xi:include href="anon-auth-provider.xml" />    
 
     <xi:include href="x509-auth-provider.xml"/>