Doc updates describing namespace changes

docs/manual/src/docbook/appendix-namespace.xml

@@ -1,657 +1,584 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <appendix version="5.0" xml:id="appendix-namespace" xmlns="http://docbook.org/ns/docbook"
-  xmlns:xlink="http://www.w3.org/1999/xlink"
-  xmlns:xi="http://www.w3.org/2001/XInclude">
-
+  xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
   <info>
     <title>The Security Namespace</title>
   </info>
-
-  <para>
-    This appendix provides a reference to the elements available in the security namespace and information on
-    the underlying beans they create (a knowledge of the individual classes and how they work together is assumed -
-    you can find more information in the project Javadoc and elsewhere in this document).
-    If you haven't used the namespace before, please read the
-    <link xlink:href="#ns-config">introductory chapter</link> on namespace configuration, 
-    as this is intended as a supplement to the information there. Using a good quality XML editor while editing a 
-    configuration based on the schema is recommended as this will provide contextual information on which elements 
-    and attributes are available as well as comments explaining their purpose.
-  </para>
-
+  <para> This appendix provides a reference to the elements available in the security namespace and
+    information on the underlying beans they create (a knowledge of the individual classes and how
+    they work together is assumed - you can find more information in the project Javadoc and
+    elsewhere in this document). If you haven't used the namespace before, please read the <link
+      xlink:href="#ns-config">introductory chapter</link> on namespace configuration, as this is
+    intended as a supplement to the information there. Using a good quality XML editor while editing
+    a configuration based on the schema is recommended as this will provide contextual information
+    on which elements and attributes are available as well as comments explaining their purpose. </para>
   <section xml:id="nsa-http">
     <title>Web Application Security - the <literal>&lt;http&gt;</literal> Element</title>
-    <para>
-      The <literal>&lt;http&gt;</literal> element encapsulates the security configuration for the web layer of your application. 
-      It creates a <classname>FilterChainProxy</classname> bean named "springSecurityFilterChain" which maintains the stack of
-      security filters which make up the web security configuration <footnote><para>See the
-      <link xlink:href="#ns-web-xml"> introductory chapter</link> for how to set up the mapping from
-        your <literal>web.xml</literal></para></footnote>. Some core filters are always created and others will
-       be added to the stack depending on the attributes child elements which are present. The positions of the standard
-      filters are fixed (see <link xlink:href="#filter-stack">the filter order table</link> in the namespace introduction),
-      removing a common source of errors with previous versions of the framework when users had to configure the
-      filter chain explicitly in the<classname>FilterChainProxy</classname> bean. You can, of course, still do this
-      if you need full control of the configuration.
-    </para>
-    <para>
-      All filters which require a reference to the <interfacename>AuthenticationManager</interfacename> will be automatically
-      injected with the internal instance created by the namespace configuration (see the
-      <link xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the <interfacename>AuthenticationManager</interfacename>).
-    </para>
-    <para>
-        The <literal>&lt;http&gt;</literal> namespace block always creates an <classname>HttpSessionContextIntegrationFilter</classname>,
-        an <classname>ExceptionTranslationFilter</classname> and a <classname>FilterSecurityInterceptor</classname>. These are fixed
-        and cannot be replaced with alternatives.
-    </para>
-
+    <para> The <literal>&lt;http&gt;</literal> element encapsulates the security configuration for
+      the web layer of your application. It creates a <classname>FilterChainProxy</classname> bean
+      named "springSecurityFilterChain" which maintains the stack of security filters which make up
+      the web security configuration <footnote>
+        <para>See the <link xlink:href="#ns-web-xml"> introductory chapter</link> for how to set up
+          the mapping from your <literal>web.xml</literal></para>
+      </footnote>. Some core filters are always created and others will be added to the stack
+      depending on the attributes child elements which are present. The positions of the standard
+      filters are fixed (see <link xlink:href="#filter-stack">the filter order table</link> in the
+      namespace introduction), removing a common source of errors with previous versions of the
+      framework when users had to configure the filter chain explicitly in
+        the<classname>FilterChainProxy</classname> bean. You can, of course, still do this if you
+      need full control of the configuration. </para>
+    <para> All filters which require a reference to the
+        <interfacename>AuthenticationManager</interfacename> will be automatically injected with the
+      internal instance created by the namespace configuration (see the <link
+        xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the
+        <interfacename>AuthenticationManager</interfacename>). </para>
+    <para> The <literal>&lt;http&gt;</literal> namespace block always creates an
+        <classname>HttpSessionContextIntegrationFilter</classname>, an
+        <classname>ExceptionTranslationFilter</classname> and a
+        <classname>FilterSecurityInterceptor</classname>. These are fixed and cannot be replaced
+      with alternatives. </para>
     <section xml:id="nsa-http-attributes">
       <title><literal>&lt;http&gt;</literal> Attributes</title>
-      <para>
-        The attributes on the <literal>&lt;http&gt;</literal> element control some of the properties on the
-        core filters.
-      </para>
+      <para> The attributes on the <literal>&lt;http&gt;</literal> element control some of the
+        properties on the core filters. </para>
       <section xml:id="nsa-servlet-api-provision">
         <title><literal>servlet-api-provision</literal></title>
-        <para>
-          Provides versions of <literal>HttpServletRequest</literal> security methods such as
-          <literal>isUserInRole()</literal> and <literal>getPrincipal()</literal> which are implemented by
-          adding a <classname>SecurityContextHolderAwareRequestFilter</classname> bean to the stack. Defaults to "true".
-        </para>
+        <para> Provides versions of <literal>HttpServletRequest</literal> security methods such as
+            <literal>isUserInRole()</literal> and <literal>getPrincipal()</literal> which are
+          implemented by adding a <classname>SecurityContextHolderAwareRequestFilter</classname>
+          bean to the stack. Defaults to "true". </para>
       </section>
-
       <section xml:id="nsa-path-type">
         <title><literal>path-type</literal></title>
-        <para>
-          Controls whether URL patterns are interpreted as ant paths (the default) or regular expressions. In practice
-          this sets a particular <interfacename>UrlMatcher</interfacename> instance on the <classname>FilterChainProxy</classname>.
-        </para>
+        <para> Controls whether URL patterns are interpreted as ant paths (the default) or regular
+          expressions. In practice this sets a particular <interfacename>UrlMatcher</interfacename>
+          instance on the <classname>FilterChainProxy</classname>. </para>
       </section>
-
       <section xml:id="nsa-lowercase-comparisons">
         <title><literal>lowercase-comparisons</literal></title>
-        <para>
-          Whether test URLs should be converted to lower case prior to comparing with defined path patterns. If unspecified,
-          defaults to "true"
-        </para>
+        <para> Whether test URLs should be converted to lower case prior to comparing with defined
+          path patterns. If unspecified, defaults to "true" </para>
       </section>
-
       <section xml:id="session-fixation-protection">
         <title><literal>session-fixation-protection</literal></title>
-        <para>
-          Indicates whether an existing session should be invalidated when a user authenticates and a new session started.
-          If set to "none" no change will be made. "newSession" will create a new empty session.
-          "migrateSession" will create a new session and copy the session attributes to the new session. Defaults to "migrateSession".
-        </para>
-        <para>
-          If enabled this will add a <classname>SessionFixationProtectionFilter</classname> to the stack. The session fixation protection
-          options on namespace-created instances of <classname>AbstractAuthenticationProcessingFilter</classname> will also be set appropriately.
-        </para>
+        <para> Indicates whether an existing session should be invalidated when a user authenticates
+          and a new session started. If set to "none" no change will be made. "newSession" will
+          create a new empty session. "migrateSession" will create a new session and copy the
+          session attributes to the new session. Defaults to "migrateSession". </para>
+        <para> If enabled this will add a <classname>SessionFixationProtectionFilter</classname> to
+          the stack. The session fixation protection options on namespace-created instances of
+            <classname>AbstractAuthenticationProcessingFilter</classname> will also be set
+          appropriately. </para>
       </section>
-
       <section xml:id="nsa-realm">
         <title><literal>realm</literal></title>
-        <para>
-          Sets the realm name used for basic authentication (if enabled). Corresponds to the <literal>realmName</literal> proerty on
-          <classname>BasicProcessingFilterEntryPoint</classname>.
-        </para>
+        <para> Sets the realm name used for basic authentication (if enabled). Corresponds to the
+            <literal>realmName</literal> proerty on
+            <classname>BasicProcessingFilterEntryPoint</classname>. </para>
       </section>
-
       <section xml:id="nsa-entry-point-ref">
         <title><literal>entry-point-ref</literal></title>
-        <para>
-          Normally the <interfacename>AuthenticationEntryPoint</interfacename> used will be set depending on which
-          authentication mechanisms have been configured. This attribute allows this behaviour to be overridden
-          by defining a customized <interfacename>AuthenticationEntryPoint</interfacename> bean which will start the authentication
-          process.
-        </para>
+        <para> Normally the <interfacename>AuthenticationEntryPoint</interfacename> used will be set
+          depending on which authentication mechanisms have been configured. This attribute allows
+          this behaviour to be overridden by defining a customized
+            <interfacename>AuthenticationEntryPoint</interfacename> bean which will start the
+          authentication process. </para>
       </section>
-
       <section xml:id="nsa-access-decision-manager-ref">
         <title><literal>access-decision-manager-ref</literal></title>
-        <para>
-          Optional attribute specifying the ID of the <interfacename>AccessDecisionManager</interfacename> implementation which should be
-          used for authorizing HTTP requests. By default an <classname>AffirmativeBased</classname> implementation is used for with
-          a <classname>RoleVoter</classname> and an <classname>AuthenticatedVoter</classname>.
-        </para>
+        <para> Optional attribute specifying the ID of the
+            <interfacename>AccessDecisionManager</interfacename> implementation which should be used
+          for authorizing HTTP requests. By default an <classname>AffirmativeBased</classname>
+          implementation is used for with a <classname>RoleVoter</classname> and an
+            <classname>AuthenticatedVoter</classname>. </para>
       </section>
-
       <section xml:id="nsa-access-denied-page">
         <title><literal>access-denied-page</literal></title>
-        <para>
-          Deprecated in favour of the <literal>access-denied-handler</literal> child element.
+        <para> Deprecated in favour of the <literal>access-denied-handler</literal> child element.
         </para>
       </section>
-
       <section xml:id="nsa-once-per-request">
         <title><literal>once-per-request</literal></title>
-        <para>
-          Corresponds to the <literal>observeOncePerRequest</literal> property of
-          <classname>FilterSecurityInterceptor</classname>. Defaults to "true".
-        </para>
+        <para> Corresponds to the <literal>observeOncePerRequest</literal> property of
+            <classname>FilterSecurityInterceptor</classname>. Defaults to "true". </para>
       </section>
-      
       <section xml:id="create-session">
         <title><literal>create-session</literal></title>
-        <para>
-          Controls the eagerness with which an HTTP session is created. If not set, defaults to "ifRequired". Other options are "always" and "never".
-          The setting of this attribute affect the <literal>allowSessionCreation</literal> and <literal>forceEagerSessionCreation</literal>
-          properties of <classname>HttpSessionContextIntegrationFilter</classname>. <literal>allowSessionCreation</literal> will always be true unless
-          this attribute is set to "never". <literal>forceEagerSessionCreation</literal> is "false" unless it is set to "always".
-          So the default configuration allows session creation but does not force it. The exception is if concurrent session control is enabled,
-          when <literal>forceEagerSessionCreation</literal> will be set to true, regardless of what the setting is here. Using "never" would
-          then cause an exception during the initialization of <classname>HttpSessionContextIntegrationFilter</classname>.
-        </para>
+        <para> Controls the eagerness with which an HTTP session is created. If not set, defaults to
+          "ifRequired". Other options are "always" and "never". The setting of this attribute affect
+          the <literal>allowSessionCreation</literal> and
+            <literal>forceEagerSessionCreation</literal> properties of
+            <classname>HttpSessionContextIntegrationFilter</classname>.
+            <literal>allowSessionCreation</literal> will always be true unless this attribute is set
+          to "never". <literal>forceEagerSessionCreation</literal> is "false" unless it is set to
+          "always". So the default configuration allows session creation but does not force it. The
+          exception is if concurrent session control is enabled, when
+            <literal>forceEagerSessionCreation</literal> will be set to true, regardless of what the
+          setting is here. Using "never" would then cause an exception during the initialization of
+            <classname>HttpSessionContextIntegrationFilter</classname>. </para>
       </section>
     </section>
-    
     <section xml:id="nsa-access-denied-handler">
       <title><literal>access-denied-handler</literal></title>
-      <para>
-        This element allows you to set the <literal>errorPage</literal> property for the default 
-        <interfacename>AccessDeniedHandler</interfacename> used by the <classname>ExceptionTranslationFilter</classname>,
-        (using the <literal>error-page</literal> attribute, or to supply your own implementation using the <literal>ref</literal>
-        attribute. See <link xlink:href="#access-denied-handler"/> for more information on the implementation details.
-      </para>
+      <para> This element allows you to set the <literal>errorPage</literal> property for the
+        default <interfacename>AccessDeniedHandler</interfacename> used by the
+          <classname>ExceptionTranslationFilter</classname>, (using the
+          <literal>error-page</literal> attribute, or to supply your own implementation using the
+          <literal>ref</literal> attribute. See <link xlink:href="#access-denied-handler"/> for more
+        information on the implementation details. </para>
     </section>
-
     <section>
       <title>The <literal>&lt;intercept-url&gt;</literal> Element</title>
-      <para>
-        This element is used to define the set of URL patterns that the application is interested in
-        and to configure how they should be handled. It is used to construct the
-        <interfacename>FilterInvocationDefinitionSource</interfacename> used by the <classname>FilterSecurityInterceptor</classname> and
-        to exclude particular patterns from the filter chain entirely (by setting the attribute <literal>filters="none"</literal>). 
-        It is also responsible for configuring a <classname>ChannelProcessingFilter</classname> if particular URLs need to be accessed
-        by HTTPS, for example.
-      </para>
-
+      <para> This element is used to define the set of URL patterns that the application is
+        interested in and to configure how they should be handled. It is used to construct the
+          <interfacename>FilterInvocationDefinitionSource</interfacename> used by the
+          <classname>FilterSecurityInterceptor</classname> and to exclude particular patterns from
+        the filter chain entirely (by setting the attribute <literal>filters="none"</literal>). It
+        is also responsible for configuring a <classname>ChannelProcessingFilter</classname> if
+        particular URLs need to be accessed by HTTPS, for example. </para>
       <section xml:id="nsa-pattern">
         <title><literal>pattern</literal></title>
-        <para>
-          The pattern which defines the URL path. The content will depend on the <literal>path-type</literal> attribute from the 
-          containing http element, so will default to ant path syntax.
-        </para>
+        <para> The pattern which defines the URL path. The content will depend on the
+            <literal>path-type</literal> attribute from the containing http element, so will default
+          to ant path syntax. </para>
       </section>
       <section xml:id="nsa-method">
         <title><literal>method</literal></title>
-        <para>
-          The HTTP Method which will be used in combination with the pattern to match an incoming request. If omitted, any method will match.
-        </para>
+        <para> The HTTP Method which will be used in combination with the pattern to match an
+          incoming request. If omitted, any method will match. </para>
       </section>
       <section xml:id="nsa-access">
         <title><literal>access</literal></title>
-        <para>
-          Lists the access attributes which will be stored in the <interfacename>FilterInvocationDefinitionSource</interfacename> for the defined 
-          URL pattern/method combination. This should be a comma-separated list of the attributes (such as role names). 
-        </para>
+        <para> Lists the access attributes which will be stored in the
+            <interfacename>FilterInvocationDefinitionSource</interfacename> for the defined URL
+          pattern/method combination. This should be a comma-separated list of the attributes (such
+          as role names). </para>
       </section>
       <section xml:id="nsa-requires-channel">
         <title><literal>requires-channel</literal></title>
-        <para>
-          Can be "http" or "https" depending on whether a particular URL pattern should be accessed over HTTP or HTTPS respectively. Alternatively
-          the value "any" can be used when there is no preference. If this attribute is present on any <literal>&lt;intercept-url&gt;</literal>
-          element, then a <classname>ChannelProcessingFilter</classname> will be added to the filter stack and its additional dependencies added
-          to the application context. See the chapter on <link xlink:href="#channel-security-config">channel security</link> for an
-          example configuration using traditional beans.
-        </para>
-        <para>
-          If a <literal>&lt;port-mappings&gt;</literal> configuration is added, this will be used to by the <classname>SecureChannelProcessor</classname>
-          and <classname>InsecureChannelProcessor</classname> beans to determine the ports used for redirecting to HTTP/HTTPS. 
-        </para>
-      </section>      
+        <para> Can be "http" or "https" depending on whether a particular URL pattern should be
+          accessed over HTTP or HTTPS respectively. Alternatively the value "any" can be used when
+          there is no preference. If this attribute is present on any
+            <literal>&lt;intercept-url&gt;</literal> element, then a
+            <classname>ChannelProcessingFilter</classname> will be added to the filter stack and its
+          additional dependencies added to the application context. See the chapter on <link
+            xlink:href="#channel-security-config">channel security</link> for an example
+          configuration using traditional beans. </para>
+        <para> If a <literal>&lt;port-mappings&gt;</literal> configuration is added, this will be
+          used to by the <classname>SecureChannelProcessor</classname> and
+            <classname>InsecureChannelProcessor</classname> beans to determine the ports used for
+          redirecting to HTTP/HTTPS. </para>
+      </section>
     </section>
-    
     <section>
       <title>The <literal>&lt;port-mappings&gt;</literal> Element</title>
-      <para>
-        By default, an instance of <classname>PortMapperImpl</classname> will be added to the configuration for use in redirecting
-        to secure and insecure URLs. This element can optionally be used to override the default mappings which that class defines. Each
-        child <literal>&lt;port-mapping&gt;</literal> element defines a pair of HTTP:HTTPS ports. The default mappings are 80:443
-        and 8080:8443. An example of overriding these can be found in the <link xlink:href="#ns-requires-channel">namespace introduction</link>.
-      </para>
+      <para> By default, an instance of <classname>PortMapperImpl</classname> will be added to the
+        configuration for use in redirecting to secure and insecure URLs. This element can
+        optionally be used to override the default mappings which that class defines. Each child
+          <literal>&lt;port-mapping&gt;</literal> element defines a pair of HTTP:HTTPS ports. The
+        default mappings are 80:443 and 8080:8443. An example of overriding these can be found in
+        the <link xlink:href="#ns-requires-channel">namespace introduction</link>. </para>
     </section>
-
     <section xml:id="nsa-form-login">
       <title>The <literal>&lt;form-login&gt;</literal> Element</title>
-      <para>
-        Used to add an <classname>UsernamePasswordAuthenticationProcessingFilter</classname> to the filter stack and an 
-        <classname>LoginUrlAuthenticationEntryPoint</classname> to the application context to provide authentication
-        on demand. This will always take precedence over other namespace-created entry points.
-        If no attributes are supplied, a login page will be generated automatically at the URL "/spring-security-login"
-        <footnote><para>This feature is really just provided for convenience and is not intended for production (where a 
-        view technology will have been chosen and can be used to render a customized login page). The class 
-        <classname>DefaultLoginPageGeneratingFilter</classname> is responsible for rendering the login
-        page and will provide login forms for both normal form login and/or OpenID if required.</para></footnote>
-        The behaviour can be customized using the following attributes.
-      </para>
-
+      <para> Used to add an <classname>UsernamePasswordAuthenticationProcessingFilter</classname> to
+        the filter stack and an <classname>LoginUrlAuthenticationEntryPoint</classname> to the
+        application context to provide authentication on demand. This will always take precedence
+        over other namespace-created entry points. If no attributes are supplied, a login page will
+        be generated automatically at the URL "/spring-security-login" <footnote>
+          <para>This feature is really just provided for convenience and is not intended for
+            production (where a view technology will have been chosen and can be used to render a
+            customized login page). The class
+              <classname>DefaultLoginPageGeneratingFilter</classname> is responsible for rendering
+            the login page and will provide login forms for both normal form login and/or OpenID if
+            required.</para>
+        </footnote> The behaviour can be customized using the following attributes. </para>
       <section>
         <title><literal>login-page</literal></title>
-        <para>
-          The URL that should be used to render the login page. Maps to the <literal>loginFormUrl</literal>
-          property of the <classname>LoginUrlAuthenticationEntryPoint</classname>. Defaults to
-          "/spring-security-login".
-        </para>
+        <para> The URL that should be used to render the login page. Maps to the
+            <literal>loginFormUrl</literal> property of the
+            <classname>LoginUrlAuthenticationEntryPoint</classname>. Defaults to
+          "/spring-security-login". </para>
       </section>
-
       <section>
         <title><literal>login-processing-url</literal></title>
-        <para>
-          Maps to the <literal>filterProcessesUrl</literal> property of <classname>UsernamePasswordAuthenticationProcessingFilter</classname>.
-          The default value is "/j_spring_security_check".
-        </para>
+        <para> Maps to the <literal>filterProcessesUrl</literal> property of
+            <classname>UsernamePasswordAuthenticationProcessingFilter</classname>. The default value
+          is "/j_spring_security_check". </para>
       </section>
-      
       <section>
         <title><literal>default-target-url</literal></title>
-        <para>Maps to the <literal>defaultTargetUrl</literal> property of <classname>UsernamePasswordAuthenticationProcessingFilter</classname>. If
-        not set, the default value is "/" (the application root). A user will be taken to this URL after logging in, provided they
-        were not asked to login while attempting to access a secured resource, when they will be taken to the originally requested URL.
-        </para>
+        <para>Maps to the <literal>defaultTargetUrl</literal> property of
+            <classname>UsernamePasswordAuthenticationProcessingFilter</classname>. If not set, the
+          default value is "/" (the application root). A user will be taken to this URL after
+          logging in, provided they were not asked to login while attempting to access a secured
+          resource, when they will be taken to the originally requested URL. </para>
       </section>
-      
       <section>
         <title><literal>always-use-default-target</literal></title>
-        <para>
-          If set to "true", the user will always start at the value given by <literal>default-target-url</literal>, regardless of how 
-          they arrived at the login page. Maps to the <literal>alwaysUseDefaultTargetUrl</literal> property of
-          <classname>UsernamePasswordAuthenticationProcessingFilter</classname>. Default value is "false".
-        </para>
+        <para> If set to "true", the user will always start at the value given by
+            <literal>default-target-url</literal>, regardless of how they arrived at the login page.
+          Maps to the <literal>alwaysUseDefaultTargetUrl</literal> property of
+            <classname>UsernamePasswordAuthenticationProcessingFilter</classname>. Default value is
+          "false". </para>
       </section>
-
       <section>
         <title><literal>authentication-failure-url</literal></title>
-        <para>
-          Maps to the <literal>authenticationFailureUrl</literal> property of <classname>UsernamePasswordAuthenticationProcessingFilter</classname>.
-          Defines the URL the browser will be redirected to on login failure. Defaults to "/spring_security_login?login_error", which will
-          be automatically handled by the automatic login page generator, re-rendering the login page with an error message.
-        </para>
+        <para> Maps to the <literal>authenticationFailureUrl</literal> property of
+            <classname>UsernamePasswordAuthenticationProcessingFilter</classname>. Defines the URL
+          the browser will be redirected to on login failure. Defaults to
+          "/spring_security_login?login_error", which will be automatically handled by the automatic
+          login page generator, re-rendering the login page with an error message. </para>
       </section>
     </section>
-    
     <section xml:id="nsa-http-basic">
       <title>The <literal>&lt;http-basic&gt;</literal> Element</title>
-      <para>
-        Adds a <classname>BasicProcessingFilter</classname> and <classname>BasicProcessingFilterEntryPoint</classname> to the
-        configuration. The latter will only be used as the configuration entry point if form-based login is not enabled.
+      <para> Adds a <classname>BasicProcessingFilter</classname> and
+          <classname>BasicProcessingFilterEntryPoint</classname> to the configuration. The latter
+        will only be used as the configuration entry point if form-based login is not enabled.
       </para>
     </section>
-
     <section xml:id="nsa-remember-me">
       <title>The <literal>&lt;remember-me&gt;</literal> Element</title>
-      <para>
-        Adds the <classname>RememberMeProcessingFilter</classname> to the stack. This in turn will
-        be configured with either a <classname>TokenBasedRememberMeServices</classname>, a <classname>PersistentTokenBasedRememberMeServices</classname>
-        or a user-specified bean implementing <interfacename>RememberMeServices</interfacename> depending on the attribute settings.
-      </para>
+      <para> Adds the <classname>RememberMeProcessingFilter</classname> to the stack. This in turn
+        will be configured with either a <classname>TokenBasedRememberMeServices</classname>, a
+          <classname>PersistentTokenBasedRememberMeServices</classname> or a user-specified bean
+        implementing <interfacename>RememberMeServices</interfacename> depending on the attribute
+        settings. </para>
       <section>
         <title><literal>data-source-ref</literal></title>
-        <para>
-          If this is set, <classname>PersistentTokenBasedRememberMeServices</classname> will be used and configured with 
-          a <classname>JdbcTokenRepositoryImpl</classname> instance.
+        <para> If this is set, <classname>PersistentTokenBasedRememberMeServices</classname> will be
+          used and configured with a <classname>JdbcTokenRepositoryImpl</classname> instance.
         </para>
       </section>
-      
       <section>
         <title><literal>token-repository-ref</literal></title>
-        <para>
-          Configures a <classname>PersistentTokenBasedRememberMeServices</classname> but allows the use of a custom
-          <interfacename>PersistentTokenRepository</interfacename> bean.
-        </para>
-      </section>      
-      
+        <para> Configures a <classname>PersistentTokenBasedRememberMeServices</classname> but allows
+          the use of a custom <interfacename>PersistentTokenRepository</interfacename> bean. </para>
+      </section>
       <section>
         <title><literal>services-ref</literal></title>
-        <para>
-          Allows complete control of the <interfacename>RememberMeServices</interfacename> implementation that will be used
-          by the filter. The value should be the Id of a bean in the application context which implements this interface.
-        </para>
-      </section> 
-      
+        <para> Allows complete control of the <interfacename>RememberMeServices</interfacename>
+          implementation that will be used by the filter. The value should be the Id of a bean in
+          the application context which implements this interface. </para>
+      </section>
       <section>
         <title><literal>token-repository-ref</literal></title>
-        <para>
-          Configures a <classname>PersistentTokenBasedRememberMeServices</classname> but allows the use of a custom
-          <interfacename>PersistentTokenRepository</interfacename> bean.
-        </para>
-      </section>       
-      
+        <para> Configures a <classname>PersistentTokenBasedRememberMeServices</classname> but allows
+          the use of a custom <interfacename>PersistentTokenRepository</interfacename> bean. </para>
+      </section>
       <section>
         <title>The <literal>key</literal> Attribute</title>
-        <para>Maps to the "key" property of <classname>AbstractRememberMeServices</classname>. Should be set to a unique
-        value to ensure that remember-me cookies are only valid within the one application <footnote><para>This doesn't affect
-          the use of <classname>PersistentTokenBasedRememberMeServices</classname>, where the tokens are stored on the server side.</para></footnote>.
-        </para>
+        <para>Maps to the "key" property of <classname>AbstractRememberMeServices</classname>.
+          Should be set to a unique value to ensure that remember-me cookies are only valid within
+          the one application <footnote>
+            <para>This doesn't affect the use of
+                <classname>PersistentTokenBasedRememberMeServices</classname>, where the tokens are
+              stored on the server side.</para>
+          </footnote>. </para>
       </section>
-
       <section>
         <title><literal>token-validity-seconds</literal></title>
-        <para>
-          Maps to the <literal>tokenValiditySeconds</literal> property of <classname>AbstractRememberMeServices</classname>. Specifies the period
-          in seconds for which the remember-me cookie should be valid. By default it will be valid for 14 days.
+        <para> Maps to the <literal>tokenValiditySeconds</literal> property of
+            <classname>AbstractRememberMeServices</classname>. Specifies the period in seconds for
+          which the remember-me cookie should be valid. By default it will be valid for 14 days.
         </para>
       </section>
-
       <section>
         <title><literal>user-service-ref</literal></title>
-        <para>
-          The remember-me services implementations require access to a <interfacename>UserDetailsService</interfacename>, so there has to be 
-          one defined in the application context. If there is only one, it will be selected and used automatically by the namespace configuration.
-          If there are multiple instances, you can specify a bean Id explicitly using this attribute.
-        </para>
+        <para> The remember-me services implementations require access to a
+            <interfacename>UserDetailsService</interfacename>, so there has to be one defined in the
+          application context. If there is only one, it will be selected and used automatically by
+          the namespace configuration. If there are multiple instances, you can specify a bean Id
+          explicitly using this attribute. </para>
       </section>
     </section>
-
     <section xml:id="nsa-concurrent-session-control">
       <title>The <literal>&lt;concurrent-session-control&gt;</literal> Element</title>
-      <para>
-        Adds support for concurrent session control, allowing limits to be placed on the number of active sessions a user can have.
-        A <classname>ConcurrentSessionFilter</classname> will be created, along with a <classname>ConcurrentSessionControllerImpl</classname>
-        and an instance of <interfacename>SessionRegistry</interfacename> (a <classname>SessionRegistryImpl</classname> instance unless the user
-        wishes to use a custom bean). The controller is registered with the namespace's <interfacename>AuthenticationManager</interfacename> 
-        (<classname>ProviderManager</classname>). Other namespace-created beans which require a reference to the <interfacename>SessionRegistry</interfacename>
-        will automatically have it injected. 
-      </para>
-      <para>
-        Note that the <literal>forceEagerSessionCreation</literal> of <classname>HttpSessionContextIntegrationFilter</classname> will
-        be set to <literal>true</literal> if concurrent session control is in use.
-      </para>
-      
+      <para> Adds support for concurrent session control, allowing limits to be placed on the number
+        of active sessions a user can have. A <classname>ConcurrentSessionFilter</classname> will be
+        created, along with a <classname>ConcurrentSessionControllerImpl</classname> and an instance
+        of <interfacename>SessionRegistry</interfacename> (a
+          <classname>SessionRegistryImpl</classname> instance unless the user wishes to use a custom
+        bean). The controller is registered with the namespace's
+          <interfacename>AuthenticationManager</interfacename>
+          (<classname>ProviderManager</classname>). Other namespace-created beans which require a
+        reference to the <interfacename>SessionRegistry</interfacename> will automatically have it
+        injected. </para>
+      <para> Note that the <literal>forceEagerSessionCreation</literal> of
+          <classname>HttpSessionContextIntegrationFilter</classname> will be set to
+          <literal>true</literal> if concurrent session control is in use. </para>
       <section>
         <title>The <literal>max-sessions</literal> attribute</title>
-        <para>Maps to the <literal>maximumSessions</literal> property of <classname>ConcurrentSessionControllerImpl</classname>.</para>
+        <para>Maps to the <literal>maximumSessions</literal> property of
+            <classname>ConcurrentSessionControllerImpl</classname>.</para>
       </section>
-
       <section>
         <title>The <literal>expired-url</literal> attribute</title>
-        <para>
-          The URL a user will be redirected to if they attempt to use a session which has been "expired" by 
-          the concurrent session controller because the user has exceeded the number of allowed sessions and has logged 
-          in again elsewhere. Should be set unless <literal>exception-if-maximum-exceeded</literal> is set.
-          If no value is supplied, an expiry message will just be written directly back to the response.
-        </para>
+        <para> The URL a user will be redirected to if they attempt to use a session which has been
+          "expired" by the concurrent session controller because the user has exceeded the number of
+          allowed sessions and has logged in again elsewhere. Should be set unless
+            <literal>exception-if-maximum-exceeded</literal> is set. If no value is supplied, an
+          expiry message will just be written directly back to the response. </para>
       </section>
-      
       <section>
         <title>The <literal>exception-if-maximum-exceeded</literal> attribute</title>
-        <para>If set to "true" a <exceptionname>ConcurrentLoginException</exceptionname> should be raised when a user 
-          attempts to exceed the maximum allowed number of sessions. The default behaviour is to expire the original session.
-        </para>
+        <para>If set to "true" a <exceptionname>ConcurrentLoginException</exceptionname> should be
+          raised when a user attempts to exceed the maximum allowed number of sessions. The default
+          behaviour is to expire the original session. </para>
       </section>
-      
       <section>
-        <title>The <literal>session-registry-alias</literal> and <literal>session-registry-ref</literal> attributes</title>
-        <para>
-          The user can supply their own <interfacename>SessionRegistry</interfacename> implementation using the
-          <literal>session-registry-ref</literal> attribute. The other concurrent session control beans will be wired
-          up to use it. 
-        </para>
-        <para>
-          It can also be useful to have a reference to the internal session registry for use in your own
-          beans or an admin interface. You can expose the interal bean using the <literal>session-registry-alias</literal>
-          attribute, giving it a name that you can use elsewhere in your configuration.
-        </para>
+        <title>The <literal>session-registry-alias</literal> and
+            <literal>session-registry-ref</literal> attributes</title>
+        <para> The user can supply their own <interfacename>SessionRegistry</interfacename>
+          implementation using the <literal>session-registry-ref</literal> attribute. The other
+          concurrent session control beans will be wired up to use it. </para>
+        <para> It can also be useful to have a reference to the internal session registry for use in
+          your own beans or an admin interface. You can expose the interal bean using the
+            <literal>session-registry-alias</literal> attribute, giving it a name that you can use
+          elsewhere in your configuration. </para>
       </section>
-
     </section>
-    
     <section xml:id="nsa-anonymous">
       <title>The <literal>&lt;anonymous&gt;</literal> Element</title>
-      <para>
-        Adds an <classname>AnonymousProcessingFilter</classname> to the stack and an <classname>AnonymousAuthenticationProvider</classname>. 
-        Required if you are using the <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> attribute.
-      </para>
+      <para> Adds an <classname>AnonymousProcessingFilter</classname> to the stack and an
+          <classname>AnonymousAuthenticationProvider</classname>. Required if you are using the
+          <literal>IS_AUTHENTICATED_ANONYMOUSLY</literal> attribute. </para>
     </section>
-    
     <section xml:id="nsa-x509">
       <title>The <literal>&lt;x509&gt;</literal> Element</title>
-      <para>
-        Adds support for X.509 authentication. An <classname>X509PreAuthenticatedProcessingFilter</classname> will be 
-        added to the stack and a <classname>PreAuthenticatedProcessingFilterEntryPoint</classname> bean will be created. The
-        latter will only be used if no other authentication mechanisms are in use (it's only functionality is to return an HTTP
-        403 error code). A <classname>PreAuthenticatedAuthenticationProvider</classname> will also be created which delegates the
-        loading of user authorities to a <interfacename>UserDetailsService</interfacename>.
-      </para>
+      <para> Adds support for X.509 authentication. An
+          <classname>X509PreAuthenticatedProcessingFilter</classname> will be added to the stack and
+        a <classname>PreAuthenticatedProcessingFilterEntryPoint</classname> bean will be created.
+        The latter will only be used if no other authentication mechanisms are in use (it's only
+        functionality is to return an HTTP 403 error code). A
+          <classname>PreAuthenticatedAuthenticationProvider</classname> will also be created which
+        delegates the loading of user authorities to a
+          <interfacename>UserDetailsService</interfacename>. </para>
       <section>
         <title>The <literal>subject-principal-regex</literal> attribute</title>
-        <para>
-          Defines a regular expression which will be used to extract the username from the certificate (for use with the
-          <interfacename>UserDetailsService</interfacename>). 
-        </para>
+        <para> Defines a regular expression which will be used to extract the username from the
+          certificate (for use with the <interfacename>UserDetailsService</interfacename>). </para>
       </section>
       <section>
         <title>The <literal>user-service-ref</literal> attribute</title>
-        <para>
-          Allows a specific <interfacename>UserDetailsService</interfacename> to be used with X.509 in the case where
-          multiple instances are configured. If not set, an attempt will be made to locate a suitable instance automatically and
-          use that.
-        </para>
+        <para> Allows a specific <interfacename>UserDetailsService</interfacename> to be used with
+          X.509 in the case where multiple instances are configured. If not set, an attempt will be
+          made to locate a suitable instance automatically and use that. </para>
       </section>
     </section>
-
     <section xml:id="nsa-openid-login">
       <title>The <literal>&lt;openid-login&gt;</literal> Element</title>
-      <para>
-        Similar to <literal>&lt;form-login&gt;</literal> and has the same attributes. The default value for <literal>login-processing-url</literal> 
-        is "/j_spring_openid_security_check". An <classname>OpenIDUsernamePasswordAuthenticationProcessingFilter</classname> and <classname>OpenIDAuthenticationProvider</classname>
-        will be registered. The latter requires a reference to a <interfacename>UserDetailsService</interfacename>. Again, this can be
-        specified by Id, using the <literal>user-service-ref</literal> attribute, or will be located automatically in the application context.
-      </para>
+      <para> Similar to <literal>&lt;form-login&gt;</literal> and has the same attributes. The
+        default value for <literal>login-processing-url</literal> is
+        "/j_spring_openid_security_check". An
+          <classname>OpenIDUsernamePasswordAuthenticationProcessingFilter</classname> and
+          <classname>OpenIDAuthenticationProvider</classname> will be registered. The latter
+        requires a reference to a <interfacename>UserDetailsService</interfacename>. Again, this can
+        be specified by Id, using the <literal>user-service-ref</literal> attribute, or will be
+        located automatically in the application context. </para>
     </section>
-
     <section xml:id="nsa-logout">
       <title>The <literal>&lt;logout&gt;</literal> Element</title>
-      <para>
-        Adds a <classname>LogoutFilter</classname> to the filter stack. This is configured 
-        with a <classname>SecurityContextLogoutHandler</classname>.
-      </para>
+      <para> Adds a <classname>LogoutFilter</classname> to the filter stack. This is configured with
+        a <classname>SecurityContextLogoutHandler</classname>. </para>
       <section>
         <title>The <literal>logout-url</literal> attribute</title>
-        <para>
-          The URL which will cause a logout (i.e. which will be processed by the filter). Defaults to "/j_spring_security_logout".
-        </para>
+        <para> The URL which will cause a logout (i.e. which will be processed by the filter).
+          Defaults to "/j_spring_security_logout". </para>
       </section>
       <section>
         <title>The <literal>logout-success-url</literal> attribute</title>
-        <para>
-          The destination URL which the user will be taken to after logging out. Defaults to "/".
-        </para>
+        <para> The destination URL which the user will be taken to after logging out. Defaults to
+          "/". </para>
       </section>
       <section>
         <title>The <literal>invalidate-session</literal> attribute</title>
-        <para>
-          Maps to the <literal>invalidateHttpSession</literal> of the <classname>SecurityContextLogoutHandler</classname>.
-          Defaults to "true", so the session will be invalidated on logout.
-        </para>
+        <para> Maps to the <literal>invalidateHttpSession</literal> of the
+            <classname>SecurityContextLogoutHandler</classname>. Defaults to "true", so the session
+          will be invalidated on logout. </para>
       </section>
     </section>
   </section>
-  
   <section>
     <title>Authentication Services</title>
-    <para>
-      If you are using the namespace, an <interfacename>AuthenticationManager</interfacename> is
-      automatically registered and will be used by all the namespace-created beans which need to reference it.
-      The bean is an instance of Spring Security's <classname>ProviderManager</classname> class, which needs to be
-      configured with a list of one or more <interfacename>AuthenticationProvider</interfacename> instances.
+    <para> Before Spring Security 3.0, an <interfacename>AuthenticationManager</interfacename> was
+      automatically registered internally. Now you must register one explicitly using the
+        <literal>&lt;authentication-manager&gt;</literal> element. This creates an instance of
+      Spring Security's <classname>ProviderManager</classname> class, which needs to be configured
+      with a list of one or more <interfacename>AuthenticationProvider</interfacename> instances.
       These can either be created using syntax elements provided by the namespace, or they can be
-      standard bean definitions, marked for addition to the list using the 
-      <literal>custom-authentication-provider</literal> element.
-    </para>
-    
-    <section>
-      <title>The &lt;authentication-provider&gt; Element</title>
-      <para>
-        This element is basically a shorthand syntax for configuring a <link xlink:href="#dao-provider"><classname>DaoAuthenticationProvider</classname></link>.
-        <classname>DaoAuthenticationProvider</classname> loads user information from a <interfacename>UserDetailsService</interfacename> and 
-        compares the username/password combination with the values supplied at login. The <interfacename>UserDetailsService</interfacename> instance
-        can be defined either by using an available namespace element (<literal>jdbc-user-service</literal> or by using the <literal>user-service-ref</literal> 
-        attribute to point to a bean defined elsewhere in the application context). You can find examples of these variations in the
-        <link xlink:href="#ns-auth-providers">namespace introduction</link>.
-      </para>
-    </section>
-    <section>
-      <title>Using <literal>&lt;custom-authentication-provider&gt;</literal> to register an AuthenticationProvider</title>
-      <para>
-        If you have written your own <interfacename>AuthenticationProvider</interfacename> implementation (or want
-        to configure one of Spring Security's own implementations as a traditional bean for some reason, then
-        you can use the following syntax to add it to the internal <classname>ProviderManager</classname>'s list:
-        <programlisting><![CDATA[
-  <bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider">
-    <security:custom-authentication-provider />
-  </bean>
-  ]]></programlisting>
-      </para>
-    </section>
-    
+      standard bean definitions, marked for addition to the list using the
+        <literal>authentication-provider</literal> element. </para>
     <section>
       <title>The <literal>&lt;authentication-manager&gt;</literal> Element</title>
-      <para>
-        Since the <interfacename>AuthenticationManager</interfacename> will be automatically registered in the application
-        context, this element is entirely optional. It allows you to define an alias name for the internal instance for use
-        in your own configuration and also to supply a link to a <interfacename>ConcurrentSessionController</interfacename>
-        if you are configuring concurrent session control yourself rather than through the namespace (a rare requirement).
-        Its use is described in the <link xlink:href="#ns-auth-manager">namespace introduction</link>.
-      </para>
+      <para> Every Spring Security application which uses the namespace must have include this
+        element somewhere. It is resposible for registering the
+          <interfacename>AuthenticationManager</interfacename> which provides authentication
+        services to the application. It also allows you to define an alias name for the internal
+        instance for use in your own configuration. Its use is described in the <link
+          xlink:href="#ns-auth-manager">namespace introduction</link>. All elements which create
+          <interfacename>AuthenticationProvider</interfacename> instances should be children of this
+        element.</para>
+      <section>
+        <title>The &lt;authentication-provider&gt; Element</title>
+        <para> This element is basically a shorthand syntax for configuring a <link
+            xlink:href="#dao-provider"><classname>DaoAuthenticationProvider</classname></link>.
+            <classname>DaoAuthenticationProvider</classname> loads user information from a
+            <interfacename>UserDetailsService</interfacename> and compares the username/password
+          combination with the values supplied at login. The
+            <interfacename>UserDetailsService</interfacename> instance can be defined either by
+          using an available namespace element (<literal>jdbc-user-service</literal> or by using the
+            <literal>user-service-ref</literal> attribute to point to a bean defined elsewhere in
+          the application context). You can find examples of these variations in the <link
+            xlink:href="#ns-auth-providers">namespace introduction</link>. </para>
+      </section>
+      <section>
+        <title>Using <literal>&lt;authentication-provider&gt;</literal> to refer to an
+            <interfacename>AuthenticationProvider</interfacename> Bean</title>
+        <para> If you have written your own <interfacename>AuthenticationProvider</interfacename>
+          implementation (or want to configure one of Spring Security's own implementations as a
+          traditional bean for some reason, then you can use the following syntax to add it to the
+          internal <classname>ProviderManager</classname>'s list: <programlisting><![CDATA[
+  <security:authentication-manager>
+    <security:authentication-provider ref="myAuthenticationProvider" />
+  </security:authentication-manager>
+  <bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>
+  ]]></programlisting></para>
+      </section>
     </section>
-    
   </section>
-  
   <section>
     <title>Method Security</title>
-    
     <section>
       <title>The <literal>&lt;global-method-security&gt;</literal> Element</title>
-      <para>
-        This element is the primary means of adding support for securing methods on Spring Security beans. Methods can
-        be secured by the use of annotations (defined at the interface or class level) or by defining a set of 
-        pointcuts as child elements, using AspectJ syntax.
-      </para>
-      <para>
-        Method security uses the same <interfacename>AccessDecisionManager</interfacename> configuration as web security,
-        but this can be overridden as explained above <xref xlink:href="#nsa-access-decision-manager-ref"/>, using the same
-        attribute.
-      </para>
+      <para> This element is the primary means of adding support for securing methods on Spring
+        Security beans. Methods can be secured by the use of annotations (defined at the interface
+        or class level) or by defining a set of pointcuts as child elements, using AspectJ syntax. </para>
+      <para> Method security uses the same <interfacename>AccessDecisionManager</interfacename>
+        configuration as web security, but this can be overridden as explained above <xref
+          xlink:href="#nsa-access-decision-manager-ref"/>, using the same attribute. </para>
       <section>
-        <title>The <literal>&lt;secured-annotations&gt;</literal> and <literal>&lt;jsr250-annotations&gt;</literal> Attributes</title>
-        <para>
-          Setting these to "true" will enable support for Spring Security's own <literal>@Secured</literal> annotations and
-          JSR-250 annotations, respectively. They are both disabled by default. Use of JSR-250 annotations also adds a
-          <classname>Jsr250Voter</classname> to the <interfacename>AccessDecisionManager</interfacename>, so you need to 
-          make sure you do this if you are using a custom implementation and want to use these annotations.
-        </para>
+        <title>The <literal>&lt;secured-annotations&gt;</literal> and
+            <literal>&lt;jsr250-annotations&gt;</literal> Attributes</title>
+        <para> Setting these to "true" will enable support for Spring Security's own
+            <literal>@Secured</literal> annotations and JSR-250 annotations, respectively. They are
+          both disabled by default. Use of JSR-250 annotations also adds a
+            <classname>Jsr250Voter</classname> to the
+            <interfacename>AccessDecisionManager</interfacename>, so you need to make sure you do
+          this if you are using a custom implementation and want to use these annotations. </para>
       </section>
       <section>
         <title>Securing Methods using <literal>&lt;protect-pointcut&gt;</literal></title>
-        <para>
-          Rather than defining security attributes on an individual method or class basis using the 
-          <literal>@Secured</literal> annotation, you can define cross-cutting security constraints across whole 
-          sets of methods and interfaces in your service layer using the <literal>&lt;protect-pointcut&gt;</literal> 
-          element. This has two attributes:
-          <itemizedlist>
-            <listitem><para><literal>expression</literal> - the pointcut expression</para></listitem>
-            <listitem><para><literal>access</literal> - the security attributes which apply</para></listitem>
-          </itemizedlist>
-          You can find an example in the <link xlink:href="#ns-protect-pointcut">namespace introduction</link>.
-        </para>
+        <para> Rather than defining security attributes on an individual method or class basis using
+          the <literal>@Secured</literal> annotation, you can define cross-cutting security
+          constraints across whole sets of methods and interfaces in your service layer using the
+            <literal>&lt;protect-pointcut&gt;</literal> element. This has two attributes: <itemizedlist>
+            <listitem>
+              <para><literal>expression</literal> - the pointcut expression</para>
+            </listitem>
+            <listitem>
+              <para><literal>access</literal> - the security attributes which apply</para>
+            </listitem>
+          </itemizedlist> You can find an example in the <link xlink:href="#ns-protect-pointcut"
+            >namespace introduction</link>. </para>
       </section>
       <section xml:id="nsa-custom-after-invocation">
-        <title>The <literal>&lt;custom-after-invocation-provider&gt;</literal> Element</title>
-        <para>
-          This element can be used to decorate an <interfacename>AfterInvocationProvider</interfacename>
-          for use by the security interceptor maintained by the <literal>&lt;global-method-security&gt;</literal>
-          namespace.
-        </para>
-        <para>
-          The syntax is the same as for <literal>&lt;custom-authentication-provider&gt;</literal>.
-        </para>
+        <title>The <literal>&lt;after-invocation-provider&gt;</literal> Element</title>
+        <para> This element can be used to decorate an
+            <interfacename>AfterInvocationProvider</interfacename> for use by the security
+          interceptor maintained by the <literal>&lt;global-method-security&gt;</literal> namespace.
+          You can define zero or more of these within the <literal>global-method-security</literal>
+          element, each with a <literal>ref</literal> attribute pointing to an
+            <interfacename>AfterInvocationProvider</interfacename> bean instance within your
+          application context. </para>
       </section>
     </section>
     <section>
       <title>LDAP Namespace Options</title>
-      <para>
-        LDAP is covered in some details in <link xlink:href="#ldap">its own chapter</link>. We will expand on that
-        here with some explanation of how the namespace options map to Spring beans. The LDAP implementation uses
-        Spring LDAP extensively, so some familiarity with that project's API may be useful. 
-      </para>
+      <para> LDAP is covered in some details in <link xlink:href="#ldap">its own chapter</link>. We
+        will expand on that here with some explanation of how the namespace options map to Spring
+        beans. The LDAP implementation uses Spring LDAP extensively, so some familiarity with that
+        project's API may be useful. </para>
       <section>
-        <title>Defining the LDAP Server using the <literal>&lt;ldap-server&gt;</literal> Element</title>
-        <para>
-          This element sets up a Spring LDAP <interfacename>ContextSource</interfacename> for use by the 
-          other LDAP beans, defining the location of the LDAP server and other information (such as a username
-          and password, if it doesn't allow anonymous access) for connecting to it. It can also be used to 
-          create an embedded server for testing. 
-          Details of the syntax for both options are covered in the <link xlink:href="#ldap-server">LDAP chapter</link>.
-          The actual <interfacename>ContextSource</interfacename> implementation is 
-          <classname>DefaultSpringSecurityContextSource</classname> which extends Spring LDAP's 
-          <classname>LdapContextSource</classname> class. The <literal>manager-dn</literal> and <literal>manager-password</literal>
-          attributes map to the latter's <literal>userDn</literal> and <literal>password</literal> properties respectively.
-        </para>
-        <para>
-          If you only have one server defined in your application context, the other LDAP namespace-defined beans
-          will use it automatically. Otherwise, you can give the element an "id" attribute and refer to it from other
-          namespace beans using the <literal>server-ref</literal> attribute. This is actually the bean Id of the 
-          <literal>ContextSource</literal> instance, if you want to use it in other traditional Spring beans.
-        </para>
+        <title>Defining the LDAP Server using the <literal>&lt;ldap-server&gt;</literal>
+          Element</title>
+        <para> This element sets up a Spring LDAP <interfacename>ContextSource</interfacename> for
+          use by the other LDAP beans, defining the location of the LDAP server and other
+          information (such as a username and password, if it doesn't allow anonymous access) for
+          connecting to it. It can also be used to create an embedded server for testing. Details of
+          the syntax for both options are covered in the <link xlink:href="#ldap-server">LDAP
+            chapter</link>. The actual <interfacename>ContextSource</interfacename> implementation
+          is <classname>DefaultSpringSecurityContextSource</classname> which extends Spring LDAP's
+            <classname>LdapContextSource</classname> class. The <literal>manager-dn</literal> and
+            <literal>manager-password</literal> attributes map to the latter's
+            <literal>userDn</literal> and <literal>password</literal> properties respectively. </para>
+        <para> If you only have one server defined in your application context, the other LDAP
+          namespace-defined beans will use it automatically. Otherwise, you can give the element an
+          "id" attribute and refer to it from other namespace beans using the
+            <literal>server-ref</literal> attribute. This is actually the bean Id of the
+            <literal>ContextSource</literal> instance, if you want to use it in other traditional
+          Spring beans. </para>
       </section>
       <section>
         <title>The <literal>&lt;ldap-provider&gt;</literal> Element</title>
-        <para>
-          This element is shorthand for the creation of an <classname>LdapAuthenticationProvider</classname> instance.
-          By default this will be configured with a <classname>BindAuthenticator</classname> instance and a 
-          <classname>DefaultAuthoritiesPopulator</classname>. 
-        </para>
+        <para> This element is shorthand for the creation of an
+            <classname>LdapAuthenticationProvider</classname> instance. By default this will be
+          configured with a <classname>BindAuthenticator</classname> instance and a
+            <classname>DefaultAuthoritiesPopulator</classname>. As with all namespace authentication
+          providers, it must be included as a child of the
+            <literal>authentication-provider</literal> element.</para>
         <section>
           <title>The <literal>user-dn-pattern</literal> Attribute</title>
-          <para>
-            If your users are at a fixed location in the directory (i.e. you can work out the DN
-            directly from the username without doing a directory search), you can use this attribute
-            to map directly to the DN. It maps directly to the <literal>userDnPatterns</literal>
-            property of <classname>AbstractLdapAuthenticator</classname>.
-          </para>
+          <para> If your users are at a fixed location in the directory (i.e. you can work out the
+            DN directly from the username without doing a directory search), you can use this
+            attribute to map directly to the DN. It maps directly to the
+              <literal>userDnPatterns</literal> property of
+              <classname>AbstractLdapAuthenticator</classname>. </para>
         </section>
-
         <section>
-          <title>The <literal>user-search-base</literal> and <literal>user-search-filter</literal> Attributes</title>
-          <para>
-            If you need to perform a search to locate the user in the directory, then you
-            can set these attributes to control the search. The <classname>BindAuthenticator</classname> will be configured
-            with a <classname>FilterBasedLdapUserSearch</classname> and the attribute values map directly to the first two
-            arguments of that bean's constructor. If these attributes aren't set and no <literal>user-dn-pattern</literal>
-            has been supplied as an alternative, then the default search values of <literal>user-search-filter="(uid={0})"</literal>
-            and <literal>user-search-base=""</literal> will be used.
-          </para>
+          <title>The <literal>user-search-base</literal> and <literal>user-search-filter</literal>
+            Attributes</title>
+          <para> If you need to perform a search to locate the user in the directory, then you can
+            set these attributes to control the search. The <classname>BindAuthenticator</classname>
+            will be configured with a <classname>FilterBasedLdapUserSearch</classname> and the
+            attribute values map directly to the first two arguments of that bean's constructor. If
+            these attributes aren't set and no <literal>user-dn-pattern</literal> has been supplied
+            as an alternative, then the default search values of
+              <literal>user-search-filter="(uid={0})"</literal> and
+              <literal>user-search-base=""</literal> will be used. </para>
         </section>
         <section>
-          <title><literal>group-search-filter</literal>, <literal>group-search-base</literal>, <literal>group-role-attribute</literal> and <literal>role-prefix</literal> Attributes</title>
-          <para>
-            The value of <literal>group-search-base</literal> is mapped to the <literal>groupSearchBase</literal> constructor argument
-            of <classname>DefaultAuthoritiesPopulator</classname> and defaults to "ou=groups". The default filter value is
-            "(uniqueMember={0})", which assumes that the entry is of type "groupOfUniqueNames". <literal>group-role-attribute</literal>
-            maps to the <literal>groupRoleAttribute</literal> attribute and defaults to "cn". Similarly <literal>role-prefix</literal>
-            maps to <literal>rolePrefix</literal> and defaults to "ROLE_".
-          </para>
+          <title><literal>group-search-filter</literal>, <literal>group-search-base</literal>,
+              <literal>group-role-attribute</literal> and <literal>role-prefix</literal>
+            Attributes</title>
+          <para> The value of <literal>group-search-base</literal> is mapped to the
+              <literal>groupSearchBase</literal> constructor argument of
+              <classname>DefaultAuthoritiesPopulator</classname> and defaults to "ou=groups". The
+            default filter value is "(uniqueMember={0})", which assumes that the entry is of type
+            "groupOfUniqueNames". <literal>group-role-attribute</literal> maps to the
+              <literal>groupRoleAttribute</literal> attribute and defaults to "cn". Similarly
+              <literal>role-prefix</literal> maps to <literal>rolePrefix</literal> and defaults to
+            "ROLE_". </para>
         </section>
         <section>
           <title>The <literal>&lt;password-compare&gt;</literal> Element</title>
-          <para>
-            This is used as child element to <literal>&lt;ldap-provider&gt;</literal>  and switches
-            the authentication strategy from <classname>BindAuthenticator</classname> to
-            <classname>PasswordComparisonAuthenticator</classname>. This can optionally be supplied with a 
-            <literal>hash</literal> attribute or with a child <literal>&lt;password-encoder&gt;</literal>
-            element to hash the password before submitting it to the directory for comparison.
-          </para>
+          <para> This is used as child element to <literal>&lt;ldap-provider&gt;</literal> and
+            switches the authentication strategy from <classname>BindAuthenticator</classname> to
+              <classname>PasswordComparisonAuthenticator</classname>. This can optionally be
+            supplied with a <literal>hash</literal> attribute or with a child
+              <literal>&lt;password-encoder&gt;</literal> element to hash the password before
+            submitting it to the directory for comparison. </para>
         </section>
       </section>
       <section>
         <title>The <literal>&lt;ldap-user-service&gt;</literal> Element</title>
-        <para>
-          This element configures an LDAP <interfacename>UserDetailsService</interfacename>. The class used
-          is <classname>LdapUserDetailsService</classname> which is a combination of a  <classname>FilterBasedLdapUserSearch</classname>
-          and a <classname>DefaultAuthoritiesPopulator</classname>. The attributes it supports have the same usage as in
-          <literal>&lt;ldap-provider&gt;</literal>.
-        </para>
+        <para> This element configures an LDAP <interfacename>UserDetailsService</interfacename>.
+          The class used is <classname>LdapUserDetailsService</classname> which is a combination of
+          a <classname>FilterBasedLdapUserSearch</classname> and a
+            <classname>DefaultAuthoritiesPopulator</classname>. The attributes it supports have the
+          same usage as in <literal>&lt;ldap-provider&gt;</literal>. </para>
       </section>
     </section>
   </section>
-
 </appendix>

docs/manual/src/docbook/namespace-config.xml

@@ -293,23 +293,32 @@
   </beans:bean>
   ]]>
         </programlisting> You can also use standard
-          <interfacename>AuthenticationProvider</interfacename> beans by adding the
-          <literal>&lt;custom-authentication-provider&gt;</literal> element within the bean
-        definition. See <xref linkend="ns-auth-manager"/> for more on this. </para>
+          <interfacename>AuthenticationProvider</interfacename> beans as follows <programlisting language="xml"><![CDATA[
+  <authentication-manager>
+    <authentication-provider ref='myAuthenticationProvider'/>
+  </authentication-manager>
+  ]]>
+        </programlisting> where <literal>myAuthenticationProvider</literal> is the name of a
+        bean in your application context which implements
+          <interfacename>AuthenticationProvider</interfacename>. See <xref linkend="ns-auth-manager"
+        /> for more on information on how the Spring Security
+          <interfacename>AuthenticationManager</interfacename> is configured using the namespace. </para>
       <section>
         <title>Adding a Password Encoder</title>
         <para> Often your password data will be encoded using a hashing algorithm. This is supported
           by the <literal>&lt;password-encoder&gt;</literal> element. With SHA encoded passwords,
           the original authentication provider configuration would look like this: <programlisting language="xml"><![CDATA[
-<authentication-provider>
-  <password-encoder hash="sha"/>
-  <user-service>
-    <user name="jimi" password="d7e6351eaa13189a5a3641bab846c8e8c69ba39f" 
+<authentication-manager>
+  <authentication-provider>
+    <password-encoder hash="sha"/>
+    <user-service>
+      <user name="jimi" password="d7e6351eaa13189a5a3641bab846c8e8c69ba39f" 
             authorities="ROLE_USER, ROLE_ADMIN" />
-    <user name="bob" password="4e7421b1b8765d8f9406d87e7cc6aa784c4ab97f" 
+      <user name="bob" password="4e7421b1b8765d8f9406d87e7cc6aa784c4ab97f" 
             authorities="ROLE_USER" />
-  </user-service>
-</authentication-provider>
+    </user-service>
+  </authentication-provider>
+</authentication-manager>
   ]]>
           </programlisting></para>
         <para> When using hashed passwords, it's also a good idea to use a salt value to protect
@@ -680,19 +689,24 @@
     </section>
   </section>
   <section xml:id="ns-auth-manager">
-    <title>The Default Authentication Manager</title>
-    <para> 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
-        <classname>ProviderManager</classname> class, which you may already be familiar with if
-      you've used the framework before. If not, it will be covered later, in <link
-        xlink:href="#tech-intro-authentication"/>. You can't use a custom
+    <title>The Authentication Manager and the Namespace</title>
+    <para> The main interface which provides authentication services in Spring Security is the
+        <interfacename>AuthenticationManager</interfacename>. This is usually an instance of Spring
+      Security's <classname>ProviderManager</classname> class, which you may already be familiar
+      with if you've used the framework before. If not, it will be covered later, in <link
+        xlink:href="#tech-intro-authentication"/>. The bean instance is registered using the
+        <literal>authentication-manager</literal> namespace element. You can't use a custom
         <classname>AuthenticationManager</classname> 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
-        <classname>AuthenticationProvider</classname>s that are used. </para>
+        <classname>AuthenticationProvider</classname>s that are used.</para>
     <para> You may want to register additional <classname>AuthenticationProvider</classname> beans
       with the <classname>ProviderManager</classname> and you can do this using the
-        <literal>&lt;custom-authentication-provider&gt;</literal> element within the bean. For
-      example: <programlisting language="xml"><![CDATA[
+        <literal>&lt;authentication-provider&gt;</literal> element with the <literal>ref</literal>
+      attribute, where the value of the attribute is the name of the provider bean you want to add.
+      For example: <programlisting language="xml"><![CDATA[
+  <authentication-manager>
+    <authentication-provider ref="casAuthenticationProvider"/>
+  </authentication-manager>
   <bean id="casAuthenticationProvider" 
       class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
     <security:custom-authentication-provider />
@@ -703,11 +717,12 @@
       the <interfacename>AuthenticationManager</interfacename>. There is a special element which
       lets you register an alias for the <interfacename>AuthenticationManager</interfacename> and
       you can then use this name elsewhere in your application context. <programlisting language="xml"><![CDATA[        
-  <security:authentication-manager alias="authenticationManager"/>
+  <security:authentication-manager alias="authenticationManager"> 
+     ...
+  </security:authentication-manager>
 
   <bean id="customizedFormLoginFilter" 
         class="com.somecompany.security.web.CustomFormLoginFilter">
-     <security:custom-filter position="AUTHENTICATION_PROCESSING_FILTER "/>
      <property name="authenticationManager" ref="authenticationManager"/>
      ...
   </bean>