SEC-624: Split ref manual into separate chapter files and added Spring styling as used by spring-ws.

src/docbkx/anon-auth-provider.xml

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">                         
+
+<chapter id="anonymous">
+<title>Anonymous Authentication</title>
+
+<sect1 id="anonymous-overview">
+    <title>Overview</title>
+    
+    <para>Particularly in the case of web request URI security, sometimes
+        it is more convenient to assign configuration attributes against every
+        possible secure object invocation. Put differently, sometimes it is
+        nice to say <literal>ROLE_SOMETHING</literal> is required by default
+        and only allow certain exceptions to this rule, such as for login,
+        logout and home pages of an application. There are also other
+        situations where anonymous authentication would be desired, such as
+        when an auditing interceptor queries the
+        <literal>SecurityContextHolder</literal> to identify which principal
+        was responsible for a given operation. Such classes can be authored
+        with more robustness if they know the
+        <literal>SecurityContextHolder</literal> always contains an
+        <literal>Authentication</literal> object, and never
+        <literal>null</literal>.</para>
+</sect1>
+
+<sect1 id="anonymous-config">
+    <title>Configuration</title>
+    
+    <para>Spring Security provides three classes that together provide an
+        anonymous authentication feature.
+        <literal>AnonymousAuthenticationToken</literal> is an implementation
+        of <literal>Authentication</literal>, and stores the
+        <literal>GrantedAuthority</literal>[]s which apply to the anonymous
+        principal. There is a corresponding
+        <literal>AnonymousAuthenticationProvider</literal>, which is chained
+        into the <literal>ProviderManager</literal> so that
+        <literal>AnonymousAuthenticationTokens</literal> are accepted.
+        Finally, there is an AnonymousProcessingFilter, which is chained after
+        the normal authentication mechanisms and automatically add an
+        <literal>AnonymousAuthenticationToken</literal> to the
+        <literal>SecurityContextHolder</literal> if there is no existing
+        <literal>Authentication</literal> held there. The definition of the
+        filter and authentication provider appears as follows:</para>
+    
+    <para><programlisting>
+        &lt;bean id="anonymousProcessingFilter"
+        class="org.springframework.security.providers.anonymous.AnonymousProcessingFilter"&gt;
+        &lt;property name="key"&gt;&lt;value&gt;foobar&lt;/value&gt;&lt;/property&gt;
+        &lt;property name="userAttribute"&gt;&lt;value&gt;anonymousUser,ROLE_ANONYMOUS&lt;/value&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="anonymousAuthenticationProvider"
+        class="org.springframework.security.providers.anonymous.AnonymousAuthenticationProvider"&gt;
+        &lt;property name="key"&gt;&lt;value&gt;foobar&lt;/value&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+    </programlisting></para>
+    
+    <para>The <literal>key</literal> is shared between the filter and
+        authentication provider, so that tokens created by the former are
+        accepted by the latter. The <literal>userAttribute</literal> is
+        expressed in the form of
+        <literal>usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]</literal>.
+        This is the same syntax as used after the equals sign for
+        <literal>InMemoryDaoImpl</literal>'s <literal>userMap</literal>
+        property.</para>
+    
+    <para>As explained earlier, the benefit of anonymous authentication is
+        that all URI patterns can have security applied to them. For
+        example:</para>
+    
+    <para><programlisting>
+        &lt;bean id="filterInvocationInterceptor"
+        class="org.springframework.security.intercept.web.FilterSecurityInterceptor"&gt;
+        &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+        &lt;property name="accessDecisionManager"&gt;&lt;ref local="httpRequestAccessDecisionManager"/&gt;&lt;/property&gt;
+        &lt;property name="objectDefinitionSource"&gt;
+        &lt;value&gt;
+        CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+        PATTERN_TYPE_APACHE_ANT
+        /index.jsp=ROLE_ANONYMOUS,ROLE_USER
+        /hello.htm=ROLE_ANONYMOUS,ROLE_USER
+        /logoff.jsp=ROLE_ANONYMOUS,ROLE_USER
+        /acegilogin.jsp*=ROLE_ANONYMOUS,ROLE_USER
+        /**=ROLE_USER
+        &lt;/value&gt;
+        &lt;/property&gt;
+        &lt;/bean&gt;
+        
+    </programlisting>Rounding out the anonymous authentication discussion
+        is the <literal>AuthenticationTrustResolver</literal> interface, with
+        its corresponding <literal>AuthenticationTrustResolverImpl</literal>
+        implementation. This interface provides an
+        <literal>isAnonymous(Authentication)</literal> method, which allows
+        interested classes to take into account this special type of
+        authentication status. The
+        <literal>ExceptionTranslationFilter</literal> uses this interface in
+        processing <literal>AccessDeniedException</literal>s. If an
+        <literal>AccessDeniedException</literal> is thrown, and the
+        authentication is of an anonymous type, instead of throwing a 403
+        (forbidden) response, the filter will instead commence the
+        <literal>AuthenticationEntryPoint</literal> so the principal can
+        authenticate properly. This is a necessary distinction, otherwise
+        principals would always be deemed "authenticated" and never be given
+        an opportunity to login via form, basic, digest or some other normal
+        authentication mechanism</para>
+</sect1>
+</chapter>

src/docbkx/authorization-common.xml

@@ -0,0 +1,573 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="authorization-common">
+  <title>Common Authorization Concepts</title>
+
+  <sect1 id="authorities">
+    <title>Authorities</title>
+
+    <para>As briefly mentioned in the Authentication section, all
+    <literal>Authentication</literal> implementations are required to
+    store an array of <literal>GrantedAuthority</literal> objects. These
+    represent the authorities that have been granted to the principal. The
+    <literal>GrantedAuthority</literal> objects are inserted into the
+    <literal>Authentication</literal> object by the
+    <literal>AuthenticationManager</literal> and are later read by
+    <literal>AccessDecisionManager</literal>s when making authorization
+    decisions.</para>
+
+    <para><literal>GrantedAuthority</literal> is an interface with only
+    one method:</para>
+
+    <para><programlisting>public String getAuthority();</programlisting></para>
+
+    <para>This method allows <literal>AccessDecisionManager</literal>s to
+    obtain a precise <literal>String</literal> representation of the
+    <literal>GrantedAuthority</literal>. By returning a representation as
+    a <literal>String</literal>, a <literal>GrantedAuthority</literal> can
+    be easily "read" by most <literal>AccessDecisionManager</literal>s. If
+    a <literal>GrantedAuthority</literal> cannot be precisely represented
+    as a <literal>String</literal>, the
+    <literal>GrantedAuthority</literal> is considered "complex" and
+    <literal>getAuthority()</literal> must return
+    <literal>null</literal>.</para>
+
+    <para>An example of a "complex" <literal>GrantedAuthority</literal>
+    would be an implementation that stores a list of operations and
+    authority thresholds that apply to different customer account numbers.
+    Representing this complex <literal>GrantedAuthority</literal> as a
+    <literal>String</literal> would be quite complex, and as a result the
+    <literal>getAuthority()</literal> method should return
+    <literal>null</literal>. This will indicate to any
+    <literal>AccessDecisionManager</literal> that it will need to
+    specifically support the <literal>GrantedAuthority</literal>
+    implementation in order to understand its contents.</para>
+
+    <para>Spring Security includes one concrete
+    <literal>GrantedAuthority</literal> implementation,
+    <literal>GrantedAuthorityImpl</literal>. This allows any
+    user-specified <literal>String</literal> to be converted into a
+    <literal>GrantedAuthority</literal>. All
+    <literal>AuthenticationProvider</literal>s included with the security
+    architecture use <literal>GrantedAuthorityImpl</literal> to populate
+    the <literal>Authentication</literal> object.</para>
+  </sect1>
+
+  <sect1 id="pre-invocation">
+    <title>Pre-Invocation Handling</title>
+
+    <para>The <literal>AccessDecisionManager</literal> is called by the
+    <literal>AbstractSecurityInterceptor</literal> and is responsible for
+    making final access control decisions. The
+    <literal>AccessDecisionManager</literal> interface contains three
+    methods:</para>
+
+    <para><programlisting>public void decide(Authentication authentication, Object object, ConfigAttributeDefinition config) throws AccessDeniedException;
+public boolean supports(ConfigAttribute attribute);
+public boolean supports(Class clazz);</programlisting></para>
+
+    <para>As can be seen from the first method, the
+    <literal>AccessDecisionManager</literal> is passed via method
+    parameters all information that is likely to be of value in assessing
+    an authorization decision. In particular, passing the secure
+    <literal>Object</literal> enables those arguments contained in the
+    actual secure object invocation to be inspected. For example, let's
+    assume the secure object was a <literal>MethodInvocation</literal>. It
+    would be easy to query the <literal>MethodInvocation</literal> for any
+    <literal>Customer</literal> argument, and then implement some sort of
+    security logic in the <literal>AccessDecisionManager</literal> to
+    ensure the principal is permitted to operate on that customer.
+    Implementations are expected to throw an
+    <literal>AccessDeniedException</literal> if access is denied.</para>
+
+    <para>The <literal>supports(ConfigAttribute)</literal> method is
+    called by the <literal>AbstractSecurityInterceptor</literal> at
+    startup time to determine if the
+    <literal>AccessDecisionManager</literal> can process the passed
+    <literal>ConfigAttribute</literal>. The
+    <literal>supports(Class)</literal> method is called by a security
+    interceptor implementation to ensure the configured
+    <literal>AccessDecisionManager</literal> supports the type of secure
+    object that the security interceptor will present.</para>
+
+    <para>Whilst users can implement their own
+    <literal>AccessDecisionManager</literal> to control all aspects of
+    authorization, Spring Security includes several
+    <literal>AccessDecisionManager</literal> implementations that are
+    based on voting. Figure 4 illustrates the relevant classes.</para>
+
+    <para><mediaobject>
+        <imageobject role="html">
+          <imagedata align="center"
+                     fileref="images/AccessDecisionVoting.gif"
+                     format="GIF" />
+        </imageobject>
+
+        <caption>
+          <para>Figure 4: Voting Decision Manager</para>
+        </caption>
+      </mediaobject></para>
+
+    <para>Using this approach, a series of
+    <literal>AccessDecisionVoter</literal> implementations are polled on
+    an authorization decision. The
+    <literal>AccessDecisionManager</literal> then decides whether or not
+    to throw an <literal>AccessDeniedException</literal> based on its
+    assessment of the votes.</para>
+
+    <para>The <literal>AccessDecisionVoter</literal> interface has three
+    methods:</para>
+
+    <para><programlisting>public int vote(Authentication authentication, Object object, ConfigAttributeDefinition config);
+public boolean supports(ConfigAttribute attribute);
+public boolean supports(Class clazz);</programlisting></para>
+
+    <para>Concrete implementations return an <literal>int</literal>, with
+    possible values being reflected in the
+    <literal>AccessDecisionVoter</literal> static fields
+    <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal>
+    and <literal>ACCESS_GRANTED</literal>. A voting implementation will
+    return <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an
+    authorization decision. If it does have an opinion, it must return
+    either <literal>ACCESS_DENIED</literal> or
+    <literal>ACCESS_GRANTED</literal>.</para>
+
+    <para>There are three concrete
+    <literal>AccessDecisionManager</literal>s provided with Spring
+    Security that tally the votes. The <literal>ConsensusBased</literal>
+    implementation will grant or deny access based on the consensus of
+    non-abstain votes. Properties are provided to control behavior in the
+    event of an equality of votes or if all votes are abstain. The
+    <literal>AffirmativeBased</literal> implementation will grant access
+    if one or more <literal>ACCESS_GRANTED</literal> votes were received
+    (ie a deny vote will be ignored, provided there was at least one grant
+    vote). Like the <literal>ConsensusBased</literal> implementation,
+    there is a parameter that controls the behavior if all voters abstain.
+    The <literal>UnanimousBased</literal> provider expects unanimous
+    <literal>ACCESS_GRANTED</literal> votes in order to grant access,
+    ignoring abstains. It will deny access if there is any
+    <literal>ACCESS_DENIED</literal> vote. Like the other implementations,
+    there is a parameter that controls the behaviour if all voters
+    abstain.</para>
+
+    <para>It is possible to implement a custom
+    <literal>AccessDecisionManager</literal> that tallies votes
+    differently. For example, votes from a particular
+    <literal>AccessDecisionVoter</literal> might receive additional
+    weighting, whilst a deny vote from a particular voter may have a veto
+    effect.</para>
+
+    <para>There are two concrete <literal>AccessDecisionVoter</literal>
+    implementations provided with Spring Security. The
+    <literal>RoleVoter</literal> class will vote if any ConfigAttribute
+    begins with <literal>ROLE_</literal>. It will vote to grant access if
+    there is a <literal>GrantedAuthority</literal> which returns a
+    <literal>String</literal> representation (via the
+    <literal>getAuthority()</literal> method) exactly equal to one or more
+    <literal>ConfigAttributes</literal> starting with
+    <literal>ROLE_</literal>. If there is no exact match of any
+    <literal>ConfigAttribute</literal> starting with
+    <literal>ROLE_</literal>, the <literal>RoleVoter</literal> will vote
+    to deny access. If no <literal>ConfigAttribute</literal> begins with
+    <literal>ROLE_</literal>, the voter will abstain.
+    <literal>RoleVoter</literal> is case sensitive on comparisons as well
+    as the <literal>ROLE_</literal> prefix.</para>
+
+    <para><literal>BasicAclEntryVoter</literal> is the other concrete
+    voter included with Spring Security. It integrates with Spring
+    Security's <literal>AclManager</literal> (discussed later). This voter
+    is designed to have multiple instances in the same application
+    context, such as:</para>
+
+    <para><programlisting>&lt;bean id="aclContactReadVoter"
+        class="org.springframework.security.vote.BasicAclEntryVoter"&gt;
+&lt;property name="processConfigAttribute"&gt;&lt;value&gt;ACL_CONTACT_READ&lt;/value&gt;&lt;/property&gt;
+&lt;property name="processDomainObjectClass"&gt;&lt;value&gt;sample.contact.Contact&lt;/value&gt;&lt;/property&gt;
+&lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
+&lt;property name="requirePermission"&gt;
+&lt;list&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.READ"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="aclContactDeleteVoter" class="org.springframework.security.vote.BasicAclEntryVoter"&gt;
+&lt;property name="processConfigAttribute"&gt;&lt;value&gt;ACL_CONTACT_DELETE&lt;/value&gt;&lt;/property&gt;
+&lt;property name="processDomainObjectClass"&gt;&lt;value&gt;sample.contact.Contact&lt;/value&gt;&lt;/property&gt;
+&lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
+&lt;property name="requirePermission"&gt;
+&lt;list&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.DELETE"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting></para>
+
+    <para>In the above example, you'd define
+    <literal>ACL_CONTACT_READ</literal> or
+    <literal>ACL_CONTACT_DELETE</literal> against some methods on a
+    <literal>MethodSecurityInterceptor</literal> or
+    <literal>AspectJSecurityInterceptor</literal>. When those methods are
+    invoked, the above applicable voter defined above would vote to grant
+    or deny access. The voter would look at the method invocation to
+    locate the first argument of type
+    <literal>sample.contact.Contact</literal>, and then pass that
+    <literal>Contact</literal> to the <literal>AclManager</literal>. The
+    <literal>AclManager</literal> will then return an access control list
+    (ACL) that applies to the current <literal>Authentication</literal>.
+    Assuming that ACL contains one of the listed
+    <literal>requirePermission</literal>s, the voter will vote to grant
+    access. If the ACL does not contain one of the permissions defined
+    against the voter, the voter will vote to deny access.
+    <literal>BasicAclEntryVoter</literal> is an important class as it
+    allows you to build truly complex applications with domain object
+    security entirely defined in the application context. If you're
+    interested in learning more about Spring Security's ACL capabilities
+    and how best to apply them, please see the ACL and "After Invocation"
+    sections of this reference guide, and the Contacts sample
+    application.</para>
+
+    <para>It is also possible to implement a custom
+    <literal>AccessDecisionVoter</literal>. Several examples are provided
+    in Spring Security unit tests, including
+    <literal>ContactSecurityVoter</literal> and
+    <literal>DenyVoter</literal>. The
+    <literal>ContactSecurityVoter</literal> abstains from voting decisions
+    where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
+    <literal>ConfigAttribute</literal> is not found. If voting, it queries
+    the <literal>MethodInvocation</literal> to extract the owner of the
+    <literal>Contact</literal> object that is subject of the method call.
+    It votes to grant access if the <literal>Contact</literal> owner
+    matches the principal presented in the
+    <literal>Authentication</literal> object. It could have just as easily
+    compared the <literal>Contact</literal> owner with some
+    <literal>GrantedAuthority</literal> the
+    <literal>Authentication</literal> object presented. All of this is
+    achieved with relatively few lines of code and demonstrates the
+    flexibility of the authorization model.</para>
+
+    <para>TODO: Remove references to the old ACL package when it's
+    deprecated, and have all references to the replacement package limited
+    to the chapter describing the new ACL implementation.</para>
+  </sect1>
+
+  <sect1 id="after-invocation">
+    <title>After Invocation Handling</title>
+
+    <para>Whilst the <literal>AccessDecisionManager</literal> is called by
+    the <literal>AbstractSecurityInterceptor</literal> before proceeding
+    with the secure object invocation, some applications need a way of
+    modifying the object actually returned by the secure object
+    invocation. Whilst you could easily implement your own AOP concern to
+    achieve this, Spring Security provides a convenient hook that has
+    several concrete implementations that integrate with its ACL
+    capabilities.</para>
+
+    <para>Figure 5 illustrates Spring Security's
+    <literal>AfterInvocationManager</literal> and its concrete
+    implementations.</para>
+
+    <para><mediaobject>
+        <imageobject>
+          <imagedata align="center" fileref="images/AfterInvocation.gif"
+                     format="GIF" />
+        </imageobject>
+
+        <caption>
+          <para>Figure 5: After Invocation Implementation</para>
+        </caption>
+      </mediaobject></para>
+
+    <para>Like many other parts of Spring Security,
+    <literal>AfterInvocationManager</literal> has a single concrete
+    implementation, <literal>AfterInvocationProviderManager</literal>,
+    which polls a list of <literal>AfterInvocationProvider</literal>s.
+    Each <literal>AfterInvocationProvider</literal> is allowed to modify
+    the return object or throw an
+    <literal>AccessDeniedException</literal>. Indeed multiple providers
+    can modify the object, as the result of the previous provider is
+    passed to the next in the list. Let's now consider our ACL-aware
+    implementations of <literal>AfterInvocationProvider</literal>.</para>
+
+    <para>Please be aware that if you're using
+    <literal>AfterInvocationManager</literal>, you will still need
+    configuration attributes that allow the
+    <literal>MethodSecurityInterceptor</literal>'s
+    <literal>AccessDecisionManager</literal> to allow an operation. If
+    you're using the typical Spring Security included
+    <literal>AccessDecisionManager</literal> implementations, having no
+    configuration attributes defined for a particular secure method
+    invocation will cause each <literal>AccessDecisionVoter</literal> to
+    abstain from voting. In turn, if the
+    <literal>AccessDecisionManager</literal> property
+    "<literal>allowIfAllAbstainDecisions</literal>" is
+    <literal>false</literal>, an <literal>AccessDeniedException</literal>
+    will be thrown. You may avoid this potential issue by either (i)
+    setting "<literal>allowIfAllAbstainDecisions</literal>" to
+    <literal>true</literal> (although this is generally not recommended)
+    or (ii) simply ensure that there is at least one configuration
+    attribute that an <literal>AccessDecisionVoter</literal> will vote to
+    grant access for. This latter (recommended) approach is usually
+    achieved through a <literal>ROLE_USER</literal> or
+    <literal>ROLE_AUTHENTICATED</literal> configuration attribute</para>
+
+    <sect2 id="after-invocation-acl-aware">
+      <title>ACL-Aware AfterInvocationProviders</title>
+
+      <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
+      ACL module. The new ACL module is a significant rewrite of the
+      existing ACL module. The new module can be found under the
+      <literal>org.springframework.security.acls</literal> package, with
+      the old ACL module under
+      <literal>org.springframework.security.acl</literal>. We encourage
+      users to consider testing with the new ACL module and build
+      applications with it. The old ACL module should be considered
+      deprecated and may be removed from a future release. The following
+      information relates to the new ACL package, and is thus
+      recommended.</para>
+
+      <para>A common services layer method we've all written at one stage
+      or another looks like this:</para>
+
+      <para><programlisting>public Contact getById(Integer id);</programlisting></para>
+
+      <para>Quite often, only principals with permission to read the
+      <literal>Contact</literal> should be allowed to obtain it. In this
+      situation the <literal>AccessDecisionManager</literal> approach
+      provided by the <literal>AbstractSecurityInterceptor</literal> will
+      not suffice. This is because the identity of the
+      <literal>Contact</literal> is all that is available before the
+      secure object is invoked. The
+      <literal>AclAfterInvocationProvider</literal> delivers a solution,
+      and is configured as follows:</para>
+
+      <para><programlisting>&lt;bean id="afterAclRead"
+          class="org.springframework.security.afterinvocation.AclEntryAfterInvocationProvider"&gt;
+&lt;constructor-arg&gt;
+&lt;ref bean="aclService"/&gt;
+&lt;/constructor-arg&gt;
+&lt;constructor-arg&gt;
+&lt;list&gt;
+  &lt;ref local="org.springframework.security.acls.domain.BasePermission.ADMINISTRATION"/&gt;
+  &lt;ref local="org.springframework.security.acls.domain.BasePermission.READ"/&gt;
+&lt;/list&gt;
+&lt;/constructor-arg&gt;
+&lt;/bean&gt;      </programlisting></para>
+
+      <para>In the above example, the <literal>Contact</literal> will be
+      retrieved and passed to the
+      <literal>AclEntryAfterInvocationProvider</literal>. The provider
+      will thrown an <literal>AccessDeniedException</literal> if one of
+      the listed <literal>requirePermission</literal>s is not held by the
+      <literal>Authentication</literal>. The
+      <literal>AclEntryAfterInvocationProvider</literal> queries the
+      <literal>Acl</literal>Service to determine the ACL that applies for
+      this domain object to this <literal>Authentication</literal>.</para>
+
+      <para>Similar to the
+      <literal>AclEntryAfterInvocationProvider</literal> is
+      <literal>AclEntryAfterInvocationCollectionFilteringProvider</literal>.
+      It is designed to remove <literal>Collection</literal> or array
+      elements for which a principal does not have access. It never thrown
+      an <literal>AccessDeniedException</literal> - simply silently
+      removes the offending elements. The provider is configured as
+      follows:</para>
+
+      <para><programlisting>&lt;bean id="afterAclCollectionRead"
+          class="org.springframework.security.afterinvocation.AclEntryAfterInvocationCollectionFilteringProvider"&gt;
+&lt;constructor-arg&gt;
+&lt;ref bean="aclService"/&gt;
+&lt;/constructor-arg&gt;
+&lt;constructor-arg&gt;
+&lt;list&gt;
+  &lt;ref local="org.springframework.security.acls.domain.BasePermission.ADMINISTRATION"/&gt;
+  &lt;ref local="org.springframework.security.acls.domain.BasePermission.READ"/&gt;
+&lt;/list&gt;
+&lt;/constructor-arg&gt;
+&lt;/bean&gt;    </programlisting></para>
+
+      <para>As you can imagine, the returned <literal>Object</literal>
+      must be a <literal>Collection</literal> or array for this provider
+      to operate. It will remove any element if the
+      <literal>AclManager</literal> indicates the
+      <literal>Authentication</literal> does not hold one of the listed
+      <literal>requirePermission</literal>s.</para>
+
+      <para>The Contacts sample application demonstrates these two
+      <literal>AfterInvocationProvider</literal>s.</para>
+    </sect2>
+
+    <sect2 id="after-invocation-acl-aware-old">
+      <title>ACL-Aware AfterInvocationProviders (old ACL module)</title>
+
+      <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
+      ACL module. The new ACL module is a significant rewrite of the
+      existing ACL module. The new module can be found under the
+      <literal>org.springframework.security.acls</literal> package, with
+      the old ACL module under
+      <literal>org.springframework.security.acl</literal>. We encourage
+      users to consider testing with the new ACL module and build
+      applications with it. The old ACL module should be considered
+      deprecated and may be removed from a future release.</para>
+
+      <para>A common services layer method we've all written at one stage
+      or another looks like this:</para>
+
+      <para><programlisting>public Contact getById(Integer id);</programlisting></para>
+
+      <para>Quite often, only principals with permission to read the
+      <literal>Contact</literal> should be allowed to obtain it. In this
+      situation the <literal>AccessDecisionManager</literal> approach
+      provided by the <literal>AbstractSecurityInterceptor</literal> will
+      not suffice. This is because the identity of the
+      <literal>Contact</literal> is all that is available before the
+      secure object is invoked. The
+      <literal>BasicAclAfterInvocationProvider</literal> delivers a
+      solution, and is configured as follows:</para>
+
+      <para><programlisting>&lt;bean id="afterAclRead"
+          class="org.springframework.security.afterinvocation.BasicAclEntryAfterInvocationProvider"&gt;
+&lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
+&lt;property name="requirePermission"&gt;
+&lt;list&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.READ"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;       </programlisting></para>
+
+      <para>In the above example, the <literal>Contact</literal> will be
+      retrieved and passed to the
+      <literal>BasicAclEntryAfterInvocationProvider</literal>. The
+      provider will thrown an <literal>AccessDeniedException</literal> if
+      one of the listed <literal>requirePermission</literal>s is not held
+      by the <literal>Authentication</literal>. The
+      <literal>BasicAclEntryAfterInvocationProvider</literal> queries the
+      <literal>AclManager</literal> to determine the ACL that applies for
+      this domain object to this <literal>Authentication</literal>.</para>
+
+      <para>Similar to the
+      <literal>BasicAclEntryAfterInvocationProvider</literal> is
+      <literal>BasicAclEntryAfterInvocationCollectionFilteringProvider</literal>.
+      It is designed to remove <literal>Collection</literal> or array
+      elements for which a principal does not have access. It never thrown
+      an <literal>AccessDeniedException</literal> - simply silently
+      removes the offending elements. The provider is configured as
+      follows:</para>
+
+      <para><programlisting>&lt;bean id="afterAclCollectionRead"
+          class="org.springframework.security.afterinvocation.BasicAclEntryAfterInvocationCollectionFilteringProvider"&gt;
+&lt;property name="aclManager"&gt;&lt;ref local="aclManager"/&gt;&lt;/property&gt;
+&lt;property name="requirePermission"&gt;
+&lt;list&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.ADMINISTRATION"/&gt;
+  &lt;ref local="org.springframework.security.acl.basic.SimpleAclEntry.READ"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;       </programlisting></para>
+
+      <para>As you can imagine, the returned <literal>Object</literal>
+      must be a <literal>Collection</literal> or array for this provider
+      to operate. It will remove any element if the
+      <literal>AclManager</literal> indicates the
+      <literal>Authentication</literal> does not hold one of the listed
+      <literal>requirePermission</literal>s.</para>
+
+      <para>The Contacts sample application demonstrates these two
+      <literal>AfterInvocationProvider</literal>s.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="authorization-taglibs">
+    <title>Authorization Tag Libraries</title>
+
+    <para><literal>AuthorizeTag</literal> is used to include content if
+    the current principal holds certain
+    <literal>GrantedAuthority</literal>s.</para>
+
+    <para>The following JSP fragment illustrates how to use the
+    <literal>AuthorizeTag</literal>:</para>
+
+    <para><programlisting>&lt;security:authorize ifAllGranted="ROLE_SUPERVISOR"&gt;
+&lt;td&gt;
+&lt;A HREF="del.htm?id=&lt;c:out value="${contact.id}"/&gt;"&gt;Del&lt;/A&gt;
+&lt;/td&gt;
+&lt;/security:authorize&gt;          </programlisting></para>
+
+    <para>This tag would cause the tag's body to be output if the
+    principal has been granted ROLE_SUPERVISOR.</para>
+
+    <para>The <literal>security:authorize</literal> tag declares the
+    following attributes:</para>
+
+    <para><itemizedlist spacing="compact">
+        <listitem>
+          <para><literal>ifAllGranted</literal>: All the listed roles must
+          be granted for the tag to output its body.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>ifAnyGranted</literal>: Any of the listed roles
+          must be granted for the tag to output its body.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>ifNotGranted</literal>: None of the listed roles
+          must be granted for the tag to output its body.</para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>You'll note that in each attribute you can list multiple roles.
+    Simply separate the roles using a comma. The
+    <literal>authorize</literal> tag ignores whitespace in
+    attributes.</para>
+
+    <para>The tag library logically ANDs all of it's parameters together.
+    This means that if you combine two or more attributes, all attributes
+    must be true for the tag to output it's body. Don't add an
+    <literal>ifAllGranted="ROLE_SUPERVISOR"</literal>, followed by an
+    <literal>ifNotGranted="ROLE_SUPERVISOR"</literal>, or you'll be
+    surprised to never see the tag's body.</para>
+
+    <para>By requiring all attributes to return true, the authorize tag
+    allows you to create more complex authorization scenarios. For
+    example, you could declare an
+    <literal>ifAllGranted="ROLE_SUPERVISOR"</literal> and an
+    <literal>ifNotGranted="ROLE_NEWBIE_SUPERVISOR"</literal> in the same
+    tag, in order to prevent new supervisors from seeing the tag body.
+    However it would no doubt be simpler to use
+    <literal>ifAllGranted="ROLE_EXPERIENCED_SUPERVISOR"</literal> rather
+    than inserting NOT conditions into your design.</para>
+
+    <para>One last item: the tag verifies the authorizations in a specific
+    order: first <literal>ifNotGranted</literal>, then
+    <literal>ifAllGranted</literal>, and finally, <literal>if
+    AnyGranted</literal>.</para>
+
+    <para><literal>AccessControlListTag</literal> is used to include
+    content if the current principal has an ACL to the indicated domain
+    object.</para>
+
+    <para>The following JSP fragment illustrates how to use the
+    <literal>AccessControlListTag</literal>:</para>
+
+    <para><programlisting>&lt;security:accesscontrollist domainObject="${contact}" hasPermission="8,16"&gt;
+&lt;td&gt;&lt;A HREF="&lt;c:url value="del.htm"&gt;&lt;c:param name="contactId" value="${contact.id}"/&gt;&lt;/c:url&gt;"&gt;Del&lt;/A&gt;&lt;/td&gt;
+&lt;/security:accesscontrollist&gt;</programlisting></para>
+
+    <para>This tag would cause the tag's body to be output if the
+    principal holds either permission 16 or permission 1 for the "contact"
+    domain object. The numbers are actually integers that are used with
+    <literal>BasePermission</literal> bit masking. Please refer to the ACL
+    section of this reference guide to understand more about the ACL
+    capabilities of Spring Security.</para>
+
+    <para><literal>AclTag</literal> is part of the old ACL module and
+    should be considered deprecated. For the sake of historical reference,
+    works exactly the samae as
+    <literal>AccessControlListTag</literal>.</para>
+  </sect1>
+</chapter>

src/docbkx/basic-authentication.xml

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+                         
+
+<chapter id="basic">
+<title>BASIC Authentication Mechanism</title>
+
+<sect1 id="basic-overview">
+    <title>Overview</title>
+    
+    <para>Spring Security provides a
+        <literal>BasicProcessingFilter</literal> which is capable of
+        processing basic authentication credentials presented in HTTP headers.
+        This can be used for authenticating calls made by Spring remoting
+        protocols (such as Hessian and Burlap), as well as normal user agents
+        (such as Internet Explorer and Navigator). The standard governing HTTP
+        Basic Authentication is defined by RFC 1945, Section 11, and the
+        <literal>BasicProcessingFilter</literal> conforms with this RFC. Basic
+        Authentication is an attractive approach to authentication, because it
+        is very widely deployed in user agents and implementation is extremely
+        simple (it's just a Base64 encoding of the username:password,
+        specified in an HTTP header).</para>
+</sect1>
+
+<sect1 id="basic-config">
+    <title>Configuration</title>
+    
+    <para>To implement HTTP Basic Authentication, it is necessary to
+        define <literal>BasicProcessingFilter</literal> in the filter chain.
+        The application context will need to define the
+        <literal>BasicProcessingFilter</literal> and its required
+        collaborator:</para>
+    
+    <para><programlisting>
+        &lt;bean id="basicProcessingFilter" class="org.springframework.security.ui.basicauth.BasicProcessingFilter"&gt;
+        &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+        &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="authenticationEntryPoint"/&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="authenticationEntryPoint"
+        class="org.springframework.security.ui.basicauth.BasicProcessingFilterEntryPoint"&gt;
+        &lt;property name="realmName"&gt;&lt;value&gt;Name Of Your Realm&lt;/value&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+    </programlisting></para>
+    
+    <para>The configured <literal>AuthenticationManager</literal>
+        processes each authentication request. If authentication fails, the
+        configured <literal>AuthenticationEntryPoint</literal> will be used to
+        retry the authentication process. Usually you will use the
+        <literal>BasicProcessingFilterEntryPoint</literal>, which returns a
+        401 response with a suitable header to retry HTTP Basic
+        authentication. If authentication is successful, the resulting
+        <literal>Authentication</literal> object will be placed into the
+        <literal>SecurityContextHolder</literal>.</para>
+    
+    <para>If the authentication event was successful, or authentication
+        was not attempted because the HTTP header did not contain a supported
+        authentication request, the filter chain will continue as normal. The
+        only time the filter chain will be interrupted is if authentication
+        fails and the <literal>AuthenticationEntryPoint</literal> is called,
+        as discussed in the previous paragraph</para>
+</sect1>
+</chapter>

src/docbkx/cas-auth-provider.xml

@@ -0,0 +1,744 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="cas">
+  <title>CAS Authentication</title>
+
+  <sect1 id="cas-overview">
+    <title>Overview</title>
+
+    <para>JA-SIG produces an enterprise-wide single sign on system known
+    as CAS. Unlike other initiatives, JA-SIG's Central Authentication
+    Service is open source, widely used, simple to understand, platform
+    independent, and supports proxy capabilities. Spring Security fully
+    supports CAS, and provides an easy migration path from
+    single-application deployments of Spring Security through to
+    multiple-application deployments secured by an enterprise-wide CAS
+    server.</para>
+
+    <para>You can learn more about CAS at
+    <literal>http://www.ja-sig.org/products/cas/</literal>. You will need
+    to visit this URL to download the CAS Server files. Whilst Spring
+    Security includes two CAS libraries in the "-with-dependencies" ZIP
+    file, you will still need the CAS Java Server Pages and
+    <literal>web.xml</literal> to customise and deploy your CAS
+    server.</para>
+  </sect1>
+
+  <sect1 id="cas-how-it-works">
+    <title>How CAS Works</title>
+
+    <para>Whilst the CAS web site above contains two documents that detail
+    the architecture of CAS, we present the general overview again here
+    within the context of Spring Security. The following refers to both
+    CAS 2.0 (produced by Yale) and CAS 3.0 (produced by JA-SIG), being the
+    versions of CAS that Spring Security supports.</para>
+
+    <para>Somewhere in your enterprise you will need to setup a CAS
+    server. The CAS server is simply a standard WAR file, so there isn't
+    anything difficult about setting up your server. Inside the WAR file
+    you will customise the login and other single sign on pages displayed
+    to users.</para>
+
+    <para>If you are deploying CAS 2.0, you will also need to specify in
+    the web.xml a <literal>PasswordHandler</literal>. The
+    <literal>PasswordHandler</literal> has a simple method that returns a
+    boolean as to whether a given username and password is valid. Your
+    <literal>PasswordHandler</literal> implementation will need to link
+    into some type of backend authentication repository, such as an LDAP
+    server or database.</para>
+
+    <para>If you are already running an existing CAS 2.0 server instance,
+    you will have already established a
+    <literal>PasswordHandler</literal>. If you do not already have a
+    <literal>PasswordHandler</literal>, you might prefer to use Spring
+    Security's <literal>CasPasswordHandler</literal> class. This class
+    delegates through to the standard Spring Security
+    <literal>AuthenticationManager</literal>, enabling you to use a
+    security configuration you might already have in place. You do not
+    need to use the <literal>CasPasswordHandler</literal> class on your
+    CAS server if you do not wish. Spring Security will function as a CAS
+    client successfully irrespective of the
+    <literal>PasswordHandler</literal> you've chosen for your CAS
+    server.</para>
+
+    <para>If you are deploying CAS 3.0, you will also need to specify an
+    <literal>AuthenticationHandler</literal> in the
+    deployerConfigContext.xml included with CAS. The
+    <literal>AuthenticationHandler</literal> has a simple method that
+    returns a boolean as to whether a given set of Credentials is valid.
+    Your <literal>AuthenticationHandler</literal> implementation will need
+    to link into some type of backend authentication repository, such as
+    an LDAP server or database. CAS itself includes numerous
+    <literal>AuthenticationHandler</literal>s out of the box to assist
+    with this.</para>
+
+    <para>If you are already running an existing CAS 3.0 server instance,
+    you will have already established an
+    <literal>AuthenticationHandler</literal>. If you do not already have
+    an <literal>AuthenticationHandler</literal>, you might prefer to use
+    Spring Security <literal>CasAuthenticationHandler</literal> class.
+    This class delegates through to the standard Spring Security
+    <literal>AuthenticationManager</literal>, enabling you to use a
+    security configuration you might already have in place. You do not
+    need to use the <literal>CasAuthenticationHandler</literal> class on
+    your CAS server if you do not wish. Spring Security will function as a
+    CAS client successfully irrespective of the
+    <literal>AuthenticationHandler</literal> you've chosen for your CAS
+    server.</para>
+
+    <para>Apart from the CAS server itself, the other key player is of
+    course the secure web applications deployed throughout your
+    enterprise. These web applications are known as "services". There are
+    two types of services: standard services and proxy services. A proxy
+    service is able to request resources from other services on behalf of
+    the user. This will be explained more fully later.</para>
+
+    <para>Services can be developed in a large variety of languages, due
+    to CAS 2.0's very light XML-based protocol. The JA-SIG CAS home page
+    contains a clients archive which demonstrates CAS clients in Java,
+    Active Server Pages, Perl, Python and others. Naturally, Java support
+    is very strong given the CAS server is written in Java. You do not
+    need to use any of CAS' client classes in applications secured by
+    Spring Security. This is handled transparently for you.</para>
+
+    <para>The basic interaction between a web browser, CAS server and n
+    Spring Security-secured service is as follows:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>The web user is browsing the service's public pages. CAS or
+        Spring Security is not involved.</para>
+      </listitem>
+
+      <listitem>
+        <para>The user eventually requests a page that is either secure or
+        one of the beans it uses is secure. Spring Security's
+        <literal>ExceptionTranslationFilter</literal> will detect the
+        <literal>AuthenticationException</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Because the user's <literal>Authentication</literal> object
+        (or lack thereof) caused an
+        <literal>AuthenticationException</literal>, the
+        <literal>ExceptionTranslationFilter</literal> will call the
+        configured <literal>AuthenticationEntryPoint</literal>. If using
+        CAS, this will be the
+        <literal>CasProcessingFilterEntryPoint</literal> class.</para>
+      </listitem>
+
+      <listitem>
+        <para>The <literal>CasProcessingFilterEntry</literal> point will
+        redirect the user's browser to the CAS server. It will also
+        indicate a <literal>service</literal> parameter, which is the
+        callback URL for Spring Security service. For example, the URL to
+        which the browser is redirected might be
+        <literal>https://my.company.com/cas/login?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_spring_cas_security_check</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>After the user's browser redirects to CAS, they will be
+        prompted for their username and password. If the user presents a
+        session cookie which indicates they've previously logged on, they
+        will not be prompted to login again (there is an exception to this
+        procedure, which we'll cover later). CAS will use the
+        <literal>PasswordHandler</literal> (or
+        <literal>AuthenticationHandler</literal> if using CAS 3.0)
+        discussed above to decide whether the username and password is
+        valid.</para>
+      </listitem>
+
+      <listitem>
+        <para>Upon successful login, CAS will redirect the user's browser
+        back to the original service. It will also include a
+        <literal>ticket</literal> parameter, which is an opaque string
+        representing the "service ticket". Continuing our earlier example,
+        the URL the browser is redirected to might be
+        <literal>https://server3.company.com/webapp/j_spring_cas_security_check?ticket=ST-0-ER94xMJmn6pha35CQRoZ</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Back in the service web application, the
+        <literal>CasProcessingFilter</literal> is always listening for
+        requests to <literal>/j_spring_cas_security_check</literal> (this
+        is configurable, but we'll use the defaults in this introduction).
+        The processing filter will construct a
+        <literal>UsernamePasswordAuthenticationToken</literal>
+        representing the service ticket. The principal will be equal to
+        <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>,
+        whilst the credentials will be the service ticket opaque value.
+        This authentication request will then be handed to the configured
+        <literal>AuthenticationManager</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>The <literal>AuthenticationManager</literal> implementation
+        will be the <literal>ProviderManager</literal>, which is in turn
+        configured with the <literal>CasAuthenticationProvider</literal>.
+        The <literal>CasAuthenticationProvider</literal> only responds to
+        <literal>UsernamePasswordAuthenticationToken</literal>s containing
+        the CAS-specific principal (such as
+        <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>)
+        and <literal>CasAuthenticationToken</literal>s (discussed
+        later).</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>CasAuthenticationProvider</literal> will validate
+        the service ticket using a <literal>TicketValidator</literal>
+        implementation. Spring Security includes one implementation, the
+        <literal>CasProxyTicketValidator</literal>. This implementation a
+        ticket validation class included in the CAS client library. The
+        <literal>CasProxyTicketValidator</literal> makes an HTTPS request
+        to the CAS server in order to validate the service ticket. The
+        <literal>CasProxyTicketValidator</literal> may also include a
+        proxy callback URL, which is included in this example:
+        <literal>https://my.company.com/cas/proxyValidate?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_spring_cas_security_check&amp;ticket=ST-0-ER94xMJmn6pha35CQRoZ&amp;pgtUrl=https://server3.company.com/webapp/casProxy/receptor</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Back on the CAS server, the proxy validation request will be
+        received. If the presented service ticket matches the service URL
+        the ticket was issued to, CAS will provide an affirmative response
+        in XML indicating the username. If any proxy was involved in the
+        authentication (discussed below), the list of proxies is also
+        included in the XML response.</para>
+      </listitem>
+
+      <listitem>
+        <para>[OPTIONAL] If the request to the CAS validation service
+        included the proxy callback URL (in the <literal>pgtUrl</literal>
+        parameter), CAS will include a <literal>pgtIou</literal> string in
+        the XML response. This <literal>pgtIou</literal> represents a
+        proxy-granting ticket IOU. The CAS server will then create its own
+        HTTPS connection back to the <literal>pgtUrl</literal>. This is to
+        mutually authenticate the CAS server and the claimed service URL.
+        The HTTPS connection will be used to send a proxy granting ticket
+        to the original web application. For example,
+        <literal>https://server3.company.com/webapp/casProxy/receptor?pgtIou=PGTIOU-0-R0zlgrl4pdAQwBvJWO3vnNpevwqStbSGcq3vKB2SqSFFRnjPHt&amp;pgtId=PGT-1-si9YkkHLrtACBo64rmsi3v2nf7cpCResXg5MpESZFArbaZiOKH</literal>.
+        We suggest you use CAS' <literal>ProxyTicketReceptor</literal>
+        servlet to receive these proxy-granting tickets, if they are
+        required.</para>
+      </listitem>
+
+      <listitem>
+        <para>The <literal>CasProxyTicketValidator</literal> will parse
+        the XML received from the CAS server. It will return to the
+        <literal>CasAuthenticationProvider</literal> a
+        <literal>TicketResponse</literal>, which includes the username
+        (mandatory), proxy list (if any were involved), and proxy-granting
+        ticket IOU (if the proxy callback was requested).</para>
+      </listitem>
+
+      <listitem>
+        <para>Next <literal>CasAuthenticationProvider</literal> will call
+        a configured <literal>CasProxyDecider</literal>. The
+        <literal>CasProxyDecider</literal> indicates whether the proxy
+        list in the <literal>TicketResponse</literal> is acceptable to the
+        service. Several implementations are provided with Spring
+        Security: <literal>RejectProxyTickets</literal>,
+        <literal>AcceptAnyCasProxy</literal> and
+        <literal>NamedCasProxyDecider</literal>. These names are largely
+        self-explanatory, except <literal>NamedCasProxyDecider</literal>
+        which allows a <literal>List</literal> of trusted proxies to be
+        provided.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>CasAuthenticationProvider</literal> will next
+        request a <literal>CasAuthoritiesPopulator</literal> to advise the
+        <literal>GrantedAuthority</literal> objects that apply to the user
+        contained in the <literal>TicketResponse</literal>. Spring
+        Security includes a <literal>DaoCasAuthoritiesPopulator</literal>
+        which simply uses the <literal>UserDetailsService</literal>
+        infrastructure to find the <literal>UserDetails</literal> and
+        their associated <literal>GrantedAuthority</literal>s. Note that
+        the password and enabled/disabled status of
+        <literal>UserDetails</literal> returned by the
+        <literal>UserDetailsService</literal> are ignored, as the CAS
+        server is responsible for authentication decisions.
+        <literal>DaoCasAuthoritiesPopulator</literal> is only concerned
+        with retrieving the <literal>GrantedAuthority</literal>s.</para>
+      </listitem>
+
+      <listitem>
+        <para>If there were no problems,
+        <literal>CasAuthenticationProvider</literal> constructs a
+        <literal>CasAuthenticationToken</literal> including the details
+        contained in the <literal>TicketResponse</literal> and the
+        <literal>GrantedAuthority</literal>s. The
+        <literal>CasAuthenticationToken</literal> contains the hash of a
+        key, so that the <literal>CasAuthenticationProvider</literal>
+        knows it created it.</para>
+      </listitem>
+
+      <listitem>
+        <para>Control then returns to
+        <literal>CasProcessingFilter</literal>, which places the created
+        <literal>CasAuthenticationToken</literal> into the
+        <literal>HttpSession</literal> attribute named
+        <literal>HttpSessionContextIntegrationFilter.SPRING_SECURITY_CONTEXT_KEY</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>The user's browser is redirected to the original page that
+        caused the <literal>AuthenticationException</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para>As the <literal>Authentication</literal> object is now in
+        the well-known location, it is handled like any other
+        authentication approach. Usually the
+        <literal>HttpSessionContextIntegrationFilter</literal> will be
+        used to associate the <literal>Authentication</literal> object
+        with the <literal>SecurityContextHolder</literal> for the duration
+        of each request.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>It's good that you're still here! It might sound involved, but
+    you can relax as Spring Security classes hide much of the complexity.
+    Let's now look at how this is configured</para>
+  </sect1>
+
+  <sect1 id="cas-server">
+    <title>Optional CAS Server Setup</title>
+
+    <para>Spring Security can even act as the backend which a CAS version
+    2.0 or 3.0 server utilises. The configuration approach is described
+    below. Of course, if you have an existing CAS environment you might
+    just like to use it instead.</para>
+
+    <sect2 id="cas-server-2">
+      <title>CAS Version 2.0</title>
+
+      <para>As mentioned above, Spring Security includes a
+      <literal>PasswordHandler</literal> that bridges your existing
+      <literal>AuthenticationManager</literal> into CAS 2.0. You do not
+      need to use this <literal>PasswordHandler</literal> to use Spring
+      Security on the client side (any CAS
+      <literal>PasswordHandler</literal> will do).</para>
+
+      <para>To install, you will need to download and extract the CAS
+      server archive. We used version 2.0.12. There will be a
+      <literal>/web</literal> directory in the root of the deployment.
+      Copy an <literal>applicationContext.xml</literal> containing your
+      <literal>AuthenticationManager</literal> as well as the
+      <literal>CasPasswordHandler</literal> into the
+      <literal>/web/WEB-INF</literal> directory. A sample
+      <literal>applicationContext.xml</literal> is included below:</para>
+
+      <programlisting>
+&lt;bean id="inMemoryDaoImpl" class="org.springframework.security.userdetails.memory.InMemoryDaoImpl"&gt;
+&lt;property name="userMap"&gt;
+&lt;value&gt;
+  rod=koala,ROLES_IGNORED_BY_CAS
+  dianne=emu,ROLES_IGNORED_BY_CAS
+  scott=wombat,ROLES_IGNORED_BY_CAS
+  peter=opal,disabled,ROLES_IGNORED_BY_CAS
+&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="daoAuthenticationProvider"
+          class="org.springframework.security.providers.dao.DaoAuthenticationProvider"&gt;
+&lt;property name="userDetailsService"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="authenticationManager" class="org.springframework.security.providers.ProviderManager"&gt;
+&lt;property name="providers"&gt;
+&lt;list&gt;
+  &lt;ref bean="daoAuthenticationProvider"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casPasswordHandler" class="org.springframework.security.adapters.cas.CasPasswordHandler"&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+    </programlisting>
+
+      <para>Note the granted authorities are ignored by CAS because it has
+      no way of communicating the granted authorities to calling
+      applications. CAS is only concerned with username and passwords (and
+      the enabled/disabled status).</para>
+
+      <para>Next you will need to edit the existing
+      <literal>/web/WEB-INF/web.xml</literal> file. Add (or edit in the
+      case of the <literal>authHandler</literal> property) the following
+      lines:</para>
+
+      <para><programlisting>
+
+&lt;context-param&gt;
+&lt;param-name&gt;edu.yale.its.tp.cas.authHandler&lt;/param-name&gt;
+&lt;param-value&gt;org.springframework.security.adapters.cas.CasPasswordHandlerProxy&lt;/param-value&gt;
+&lt;/context-param&gt;
+
+&lt;context-param&gt;
+&lt;param-name&gt;contextConfigLocation&lt;/param-name&gt;
+&lt;param-value&gt;/WEB-INF/applicationContext.xml&lt;/param-value&gt;
+&lt;/context-param&gt;
+
+&lt;listener&gt;
+&lt;listener-class&gt;org.springframework.web.context.ContextLoaderListener&lt;/listener-class&gt;
+&lt;/listener&gt;
+
+    </programlisting></para>
+
+      <para>Copy the <literal>spring.jar</literal> and
+      <literal>acegi-security.jar</literal> files into
+      <literal>/web/WEB-INF/lib</literal>. Now use the <literal>ant
+      dist</literal> task in the <literal>build.xml</literal> in the root
+      of the directory structure. This will create
+      <literal>/lib/cas.war</literal>, which is ready for deployment to
+      your servlet container.</para>
+
+      <para>Note CAS heavily relies on HTTPS. You can't even test the
+      system without an HTTPS certificate. Whilst you should refer to your
+      web container's documentation on setting up HTTPS, if you need some
+      additional help or a test certificate you might like to check the
+      <literal>samples/contacts/etc/ssl</literal> directory</para>
+    </sect2>
+
+    <sect2 id="cas-server-3">
+      <title>CAS Version 3.0</title>
+
+      <para>As mentioned above, Spring Security includes an
+      <literal>AuthenticationHandler</literal> that bridges your existing
+      <literal>AuthenticationManager</literal> into CAS 3.0. You do not
+      need to use this <literal>AuthenticationHandler</literal> to use
+      Spring Security on the client side (any CAS
+      <literal>AuthenticationHandler</literal> will do).</para>
+
+      <para>To install, you will need to download and extract the CAS
+      server archive. We used version 3.0.4. There will be a
+      <literal>/webapp</literal> directory in the root of the deployment.
+      Edit the an <literal>deployerConfigContext.xml</literal> so that it
+      contains your <literal>AuthenticationManager</literal> as well as
+      the <literal>CasAuthenticationHandler</literal>. A sample
+      <literal>applicationContext.xml</literal> is included below:</para>
+
+      <programlisting>
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;!DOCTYPE beans PUBLIC  "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"&gt;
+&lt;beans&gt;
+	&lt;bean
+		id="authenticationManager"
+		class="org.jasig.cas.authentication.AuthenticationManagerImpl"&gt;
+		&lt;property name="credentialsToPrincipalResolvers"&gt;
+			&lt;list&gt;
+				&lt;bean class="org.jasig.cas.authentication.principal.UsernamePasswordCredentialsToPrincipalResolver" /&gt;
+				&lt;bean class="org.jasig.cas.authentication.principal.HttpBasedServiceCredentialsToPrincipalResolver" /&gt;
+			&lt;/list&gt;
+		&lt;/property&gt;
+
+		&lt;property name="authenticationHandlers"&gt;
+			&lt;list&gt;
+				&lt;bean class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler" /&gt;
+				&lt;bean class="org.springframework.security.adapters.cas3.CasAuthenticationHandler"&gt;
+					&lt;property name="authenticationManager" ref="authenticationManager" /&gt;
+				&lt;/bean&gt;
+			&lt;/list&gt;
+		&lt;/property&gt;
+	&lt;/bean&gt;
+
+
+	&lt;bean id="inMemoryDaoImpl" class="org.springframework.security.userdetails.memory.InMemoryDaoImpl"&gt;
+  		&lt;property name="userMap"&gt;
+			&lt;value&gt;
+				rod=koala,ROLES_IGNORED_BY_CAS
+				dianne=emu,ROLES_IGNORED_BY_CAS
+				scott=wombat,ROLES_IGNORED_BY_CAS
+				peter=opal,disabled,ROLES_IGNORED_BY_CAS
+			&lt;/value&gt;
+		&lt;/property&gt;
+	&lt;/bean&gt;
+
+	&lt;bean id="daoAuthenticationProvider"
+          class="org.springframework.security.providers.dao.DaoAuthenticationProvider"&gt;
+     	&lt;property name="userDetailsService"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
+	&lt;/bean&gt;
+
+	&lt;bean id="authenticationManager" class="org.springframework.security.providers.ProviderManager"&gt;
+		&lt;property name="providers"&gt;
+		  &lt;list&gt;
+		    &lt;ref bean="daoAuthenticationProvider"/&gt;
+		  &lt;/list&gt;
+		&lt;/property&gt;
+	&lt;/bean&gt;
+&lt;/beans&gt;
+
+    </programlisting>
+
+      <para>Note the granted authorities are ignored by CAS because it has
+      no way of communicating the granted authorities to calling
+      applications. CAS is only concerned with username and passwords (and
+      the enabled/disabled status).</para>
+
+      <para>Copy <literal>acegi-security.jar</literal> and
+      <literal>acegi-security-cas.jar</literal> files into
+      <literal>/localPlugins/lib</literal>. Now use the <literal>ant
+      war</literal> task in the <literal>build.xml</literal> in the
+      /localPlugins directory. This will create
+      <literal>/localPlugins/target/cas.war</literal>, which is ready for
+      deployment to your servlet container.</para>
+
+      <para>Note CAS heavily relies on HTTPS. You can't even test the
+      system without an HTTPS certificate. Whilst you should refer to your
+      web container's documentation on setting up HTTPS, if you need some
+      additional help or a test certificate you might like to check the
+      CAS documentation on setting up SSL:
+      <literal>http://www.ja-sig.org/products/cas/server/ssl/index.html</literal></para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="cas-client">
+    <title>Configuration of CAS Client</title>
+
+    <para>The web application side of CAS is made easy due to Spring
+    Security. It is assumed you already know the basics of using Spring
+    Security, so these are not covered again below. Only the CAS-specific
+    beans are mentioned.</para>
+
+    <para>You will need to add a <literal>ServiceProperties</literal> bean
+    to your application context. This represents your service:</para>
+
+    <para><programlisting>
+
+&lt;bean id="serviceProperties" class="org.springframework.security.ui.cas.ServiceProperties"&gt;
+&lt;property name="service"&gt;&lt;value&gt;https://localhost:8443/contacts-cas/j_spring_cas_security_check&lt;/value&gt;&lt;/property&gt;
+&lt;property name="sendRenew"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+    </programlisting></para>
+
+    <para>The <literal>service</literal> must equal a URL that will be
+    monitored by the <literal>CasProcessingFilter</literal>. The
+    <literal>sendRenew</literal> defaults to false, but should be set to
+    true if your application is particularly sensitive. What this
+    parameter does is tell the CAS login service that a single sign on
+    login is unacceptable. Instead, the user will need to re-enter their
+    username and password in order to gain access to the service.</para>
+
+    <para>The following beans should be configured to commence the CAS
+    authentication process:</para>
+
+    <para><programlisting>
+&lt;bean id="casProcessingFilter" class="org.springframework.security.ui.cas.CasProcessingFilter"&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/casfailed.jsp&lt;/value&gt;&lt;/property&gt;
+&lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/&lt;/value&gt;&lt;/property&gt;
+&lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_spring_cas_security_check&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="exceptionTranslationFilter" class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
+&lt;property name="authenticationEntryPoint"&gt;&lt;ref local="casProcessingFilterEntryPoint"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casProcessingFilterEntryPoint"
+        class="org.springframework.security.ui.cas.CasProcessingFilterEntryPoint"&gt;
+&lt;property name="loginUrl"&gt;&lt;value&gt;https://localhost:8443/cas/login&lt;/value&gt;&lt;/property&gt;
+&lt;property name="serviceProperties"&gt;&lt;ref bean="serviceProperties"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+    </programlisting></para>
+
+    <para>You will also need to add the
+    <literal>CasProcessingFilter</literal> to web.xml:</para>
+
+    <para><programlisting>
+&lt;filter&gt;
+&lt;filter-name&gt;Spring Security CAS Processing Filter&lt;/filter-name&gt;
+&lt;filter-class&gt;org.springframework.security.util.FilterToBeanProxy&lt;/filter-class&gt;
+&lt;init-param&gt;
+&lt;param-name&gt;targetClass&lt;/param-name&gt;
+&lt;param-value&gt;org.springframework.security.ui.cas.CasProcessingFilter&lt;/param-value&gt;
+&lt;/init-param&gt;
+&lt;/filter&gt;
+
+&lt;filter-mapping&gt;
+&lt;filter-name&gt;Spring Security CAS Processing Filter&lt;/filter-name&gt;
+&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+&lt;/filter-mapping&gt;
+
+    </programlisting></para>
+
+    <para>The <literal>CasProcessingFilter</literal> has very similar
+    properties to the <literal>AuthenticationProcessingFilter</literal>
+    (used for form-based logins). Each property is
+    self-explanatory.</para>
+
+    <para>For CAS to operate, the
+    <literal>ExceptionTranslationFilter</literal> must have its
+    <literal>authenticationEntryPoint</literal> property set to the
+    <literal>CasProcessingFilterEntryPoint</literal> bean.</para>
+
+    <para>The <literal>CasProcessingFilterEntryPoint</literal> must refer
+    to the <literal>ServiceProperties</literal> bean (discussed above),
+    which provides the URL to the enterprise's CAS login server. This is
+    where the user's browser will be redirected.</para>
+
+    <para>Next you need to add an <literal>AuthenticationManager</literal>
+    that uses <literal>CasAuthenticationProvider</literal> and its
+    collaborators:</para>
+
+    <para><programlisting>
+&lt;bean id="authenticationManager" class="org.springframework.security.providers.ProviderManager"&gt;
+&lt;property name="providers"&gt;
+&lt;list&gt;
+  &lt;ref bean="casAuthenticationProvider"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casAuthenticationProvider"
+        class="org.springframework.security.providers.cas.CasAuthenticationProvider"&gt;
+&lt;property name="casAuthoritiesPopulator"&gt;&lt;ref bean="casAuthoritiesPopulator"/&gt;&lt;/property&gt;
+&lt;property name="casProxyDecider"&gt;&lt;ref bean="casProxyDecider"/&gt;&lt;/property&gt;
+&lt;property name="ticketValidator"&gt;&lt;ref bean="casProxyTicketValidator"/&gt;&lt;/property&gt;
+&lt;property name="statelessTicketCache"&gt;&lt;ref bean="statelessTicketCache"/&gt;&lt;/property&gt;
+&lt;property name="key"&gt;&lt;value&gt;my_password_for_this_auth_provider_only&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casProxyTicketValidator"
+        class="org.springframework.security.providers.cas.ticketvalidator.CasProxyTicketValidator"&gt;
+&lt;property name="casValidate"&gt;&lt;value&gt;https://localhost:8443/cas/proxyValidate&lt;/value&gt;&lt;/property&gt;
+&lt;property name="proxyCallbackUrl"&gt;&lt;value&gt;https://localhost:8443/contacts-cas/casProxy/receptor&lt;/value&gt;&lt;/property&gt;
+&lt;property name="serviceProperties"&gt;&lt;ref bean="serviceProperties"/&gt;&lt;/property&gt;
+&lt;!-- &lt;property name="trustStore"&gt;&lt;value&gt;/some/path/to/your/lib/security/cacerts&lt;/value&gt;&lt;/property&gt; --&gt;
+&lt;/bean&gt;
+
+&lt;bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"&gt;
+&lt;property name="configLocation"&gt;
+&lt;value&gt;classpath:/ehcache-failsafe.xml&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="ticketCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean"&gt;
+&lt;property name="cacheManager"&gt;
+&lt;ref local="cacheManager"/&gt;
+&lt;/property&gt;
+&lt;property name="cacheName"&gt;
+&lt;value&gt;ticketCache&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="statelessTicketCache" class="org.springframework.security.providers.cas.cache.EhCacheBasedTicketCache"&gt;
+&lt;property name="cache"&gt;&lt;ref local="ticketCacheBackend"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casAuthoritiesPopulator"
+        class="org.springframework.security.providers.cas.populator.DaoCasAuthoritiesPopulator"&gt;
+&lt;property name="userDetailsService"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="casProxyDecider" class="org.springframework.security.providers.cas.proxy.RejectProxyTickets"/&gt;
+
+    </programlisting></para>
+
+    <para>The beans are all reasonable self-explanatory if you refer back
+    to the "How CAS Works" section. Careful readers might notice one
+    surprise: the <literal>statelessTicketCache</literal> property of the
+    <literal>CasAuthenticationProvider</literal>. This is discussed in
+    detail in the "Advanced CAS Usage" section.</para>
+
+    <para>Note the <literal>CasProxyTicketValidator</literal> has a
+    remarked out <literal>trustStore</literal> property. This property
+    might be helpful if you experience HTTPS certificate issues. Also note
+    the <literal>proxyCallbackUrl</literal> is set so the service can
+    receive a proxy-granting ticket. As mentioned above, this is optional
+    and unnecessary if you do not require proxy-granting tickets. If you
+    do use this feature, you will need to configure a suitable servlet to
+    receive the proxy-granting tickets. We suggest you use CAS'
+    <literal>ProxyTicketReceptor</literal> by adding the following to your
+    web application's <literal>web.xml</literal>:</para>
+
+    <para><programlisting>
+&lt;servlet&gt;
+&lt;servlet-name&gt;casproxy&lt;/servlet-name&gt;
+&lt;servlet-class&gt;edu.yale.its.tp.cas.proxy.ProxyTicketReceptor&lt;/servlet-class&gt;
+&lt;/servlet&gt;
+
+&lt;servlet-mapping&gt;
+&lt;servlet-name&gt;casproxy&lt;/servlet-name&gt;
+&lt;url-pattern&gt;/casProxy/*&lt;/url-pattern&gt;
+&lt;/servlet-mapping&gt;
+
+    </programlisting></para>
+
+    <para>This completes the configuration of CAS. If you haven't made any
+    mistakes, your web application should happily work within the
+    framework of CAS single sign on. No other parts of Spring Security
+    need to be concerned about the fact CAS handled authentication.</para>
+
+    <para>There is also a <literal>contacts-cas.war</literal> file in the
+    sample applications directory. This sample application uses the above
+    settings and can be deployed to see CAS in operation</para>
+  </sect1>
+
+  <sect1 id="cas-advanced">
+    <title>Advanced Issues</title>
+
+    <para>The <literal>CasAuthenticationProvider</literal> distinguishes
+    between stateful and stateless clients. A stateful client is
+    considered any that originates via the
+    <literal>CasProcessingFilter</literal>. A stateless client is any that
+    presents an authentication request via the
+    <literal>UsernamePasswordAuthenticationToken</literal> with a
+    principal equal to
+    <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>.</para>
+
+    <para>Stateless clients are likely to be via remoting protocols such
+    as Hessian and Burlap. The <literal>BasicProcessingFilter</literal> is
+    still used in this case, but the remoting protocol client is expected
+    to present a username equal to the static string above, and a password
+    equal to a CAS service ticket. Clients should acquire a CAS service
+    ticket directly from the CAS server.</para>
+
+    <para>Because remoting protocols have no way of presenting themselves
+    within the context of an <literal>HttpSession</literal>, it isn't
+    possible to rely on the <literal>HttpSession</literal>'s
+    <literal>HttpSessionContextIntegrationFilter.SPRING_SECURITY_CONTEXT_KEY</literal>
+    attribute to locate the <literal>CasAuthenticationToken</literal>.
+    Furthermore, because the CAS server invalidates a service ticket after
+    it has been validated by the <literal>TicketValidator</literal>,
+    presenting the same service ticket on subsequent requests will not
+    work. It is similarly very difficult to obtain a proxy-granting ticket
+    for a remoting protocol client, as they are often deployed on client
+    machines which rarely have HTTPS URLs that would be accessible to the
+    CAS server.</para>
+
+    <para>One obvious option is to not use CAS at all for remoting
+    protocol clients. However, this would eliminate many of the desirable
+    features of CAS.</para>
+
+    <para>As a middle-ground, the
+    <literal>CasAuthenticationProvider</literal> uses a
+    <literal>StatelessTicketCache</literal>. This is used solely for
+    requests with a principal equal to
+    <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>. What
+    happens is the <literal>CasAuthenticationProvider</literal> will store
+    the resulting <literal>CasAuthenticationToken</literal> in the
+    <literal>StatelessTicketCache</literal>, keyed on the service ticket.
+    Accordingly, remoting protocol clients can present the same service
+    ticket and the <literal>CasAuthenticationProvider</literal> will not
+    need to contact the CAS server for validation (aside from the first
+    request).</para>
+
+    <para>The other aspect of advanced CAS usage involves creating proxy
+    tickets from the proxy-granting ticket. As indicated above, we
+    recommend you use CAS' <literal>ProxyTicketReceptor</literal> to
+    receive these tickets. The <literal>ProxyTicketReceptor</literal>
+    provides a static method that enables you to obtain a proxy ticket by
+    presenting the proxy-granting IOU ticket. You can obtain the
+    proxy-granting IOU ticket by calling
+    <literal>CasAuthenticationToken.getProxyGrantingTicketIou()</literal>.</para>
+
+    <para>It is hoped you find CAS integration easy and useful with Spring
+    Security classes. Welcome to enterprise-wide single sign on!</para>
+  </sect1>
+</chapter>

src/docbkx/channel-security.xml

@@ -0,0 +1,187 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+                         
+                         
+<chapter id="channel-security">
+
+<title>Channel Security</title>
+
+<sect1 id="channel-security-overview">
+    <title>Overview</title>
+    
+    <para>In addition to coordinating the authentication and authorization
+        requirements of your application, Spring Security is also able to
+        ensure unauthenticated web requests have certain properties. These
+        properties may include being of a particular transport type, having a
+        particular <literal>HttpSession</literal> attribute set and so on. The
+        most common requirement is for your web requests to be received using
+        a particular transport protocol, such as HTTPS.</para>
+    
+    <para>An important issue in considering transport security is that of
+        session hijacking. Your web container manages a
+        <literal>HttpSession</literal> by reference to a
+        <literal>jsessionid</literal> that is sent to user agents either via a
+        cookie or URL rewriting. If the <literal>jsessionid</literal> is ever
+        sent over HTTP, there is a possibility that session identifier can be
+        intercepted and used to impersonate the user after they complete the
+        authentication process. This is because most web containers maintain
+        the same session identifier for a given user, even after they switch
+        from HTTP to HTTPS pages.</para>
+    
+    <para>If session hijacking is considered too significant a risk for
+        your particular application, the only option is to use HTTPS for every
+        request. This means the <literal>jsessionid</literal> is never sent
+        across an insecure channel. You will need to ensure your
+        <literal>web.xml</literal>-defined
+        <literal>&lt;welcome-file&gt;</literal> points to an HTTPS location,
+        and the application never directs the user to an HTTP location. Spring
+        Security provides a solution to assist with the latter.</para>
+</sect1>
+
+<sect1 id="channel-security-config">
+    <title>Configuration</title>
+    
+    <para>To utilise Spring Security's channel security services, add the
+        following lines to <literal>web.xml</literal>:</para>
+    
+    <para><programlisting>
+        &lt;filter&gt;
+        &lt;filter-name&gt;Spring Security Channel Processing Filter&lt;/filter-name&gt;
+        &lt;filter-class&gt;org.springframework.security.util.FilterToBeanProxy&lt;/filter-class&gt;
+        &lt;init-param&gt;
+        &lt;param-name&gt;targetClass&lt;/param-name&gt;
+        &lt;param-value&gt;org.springframework.security.securechannel.ChannelProcessingFilter&lt;/param-value&gt;
+        &lt;/init-param&gt;
+        &lt;/filter&gt;
+        
+        &lt;filter-mapping&gt;
+        &lt;filter-name&gt;Spring Security Channel Processing Filter&lt;/filter-name&gt;
+        &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+        &lt;/filter-mapping&gt;
+        
+    </programlisting></para>
+    
+    <para>As usual when running <literal>FilterToBeanProxy</literal>, you
+        will also need to configure the filter in your application
+        context:</para>
+    
+    <para><programlisting>
+        &lt;bean id="channelProcessingFilter" class="org.springframework.security.securechannel.ChannelProcessingFilter"&gt;
+        &lt;property name="channelDecisionManager"&gt;&lt;ref bean="channelDecisionManager"/&gt;&lt;/property&gt;
+        &lt;property name="filterInvocationDefinitionSource"&gt;
+        &lt;value&gt;
+        CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+        \A/secure/.*\Z=REQUIRES_SECURE_CHANNEL
+        \A/acegilogin.jsp.*\Z=REQUIRES_SECURE_CHANNEL
+        \A/j_spring_security_check.*\Z=REQUIRES_SECURE_CHANNEL
+        \A.*\Z=REQUIRES_INSECURE_CHANNEL
+        &lt;/value&gt;
+        &lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="channelDecisionManager" class="org.springframework.security.securechannel.ChannelDecisionManagerImpl"&gt;
+        &lt;property name="channelProcessors"&gt;
+        &lt;list&gt;
+        &lt;ref bean="secureChannelProcessor"/&gt;
+        &lt;ref bean="insecureChannelProcessor"/&gt;
+        &lt;/list&gt;
+        &lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="secureChannelProcessor" class="org.springframework.security.securechannel.SecureChannelProcessor"/&gt;
+        &lt;bean id="insecureChannelProcessor" class="org.springframework.security.securechannel.InsecureChannelProcessor"/&gt;
+        
+    </programlisting></para>
+    
+    <para>Like <literal>FilterSecurityInterceptor</literal>, Apache Ant
+        style paths are also supported by the
+        <literal>ChannelProcessingFilter</literal>.</para>
+    
+    <para>The <literal>ChannelProcessingFilter</literal> operates by
+        filtering all web requests and determining the configuration
+        attributes that apply. It then delegates to the
+        <literal>ChannelDecisionManager</literal>. The default implementation,
+        <literal>ChannelDecisionManagerImpl</literal>, should suffice in most
+        cases. It simply delegates through the list of configured
+        <literal>ChannelProcessor</literal> instances. A
+        <literal>ChannelProcessor</literal> will review the request, and if it
+        is unhappy with the request (eg it was received across the incorrect
+        transport protocol), it will perform a redirect, throw an exception or
+        take whatever other action is appropriate.</para>
+    
+    <para>Included with Spring Security are two concrete
+        <literal>ChannelProcessor</literal> implementations:
+        <literal>SecureChannelProcessor</literal> ensures requests with a
+        configuration attribute of <literal>REQUIRES_SECURE_CHANNEL</literal>
+        are received over HTTPS, whilst
+        <literal>InsecureChannelProcessor</literal> ensures requests with a
+        configuration attribute of
+        <literal>REQUIRES_INSECURE_CHANNEL</literal> are received over HTTP.
+        Both implementations delegate to a
+        <literal>ChannelEntryPoint</literal> if the required transport
+        protocol is not used. The two <literal>ChannelEntryPoint</literal>
+        implementations included with Spring Security simply redirect the
+        request to HTTP and HTTPS as appropriate. Appropriate defaults are
+        assigned to the <literal>ChannelProcessor</literal> implementations
+        for the configuration attribute keywords they respond to and the
+        <literal>ChannelEntryPoint</literal> they delegate to, although you
+        have the ability to override these using the application
+        context.</para>
+    
+    <para>Note that the redirections are absolute (eg
+        <literal>http://www.company.com:8080/app/page</literal>), not relative
+        (eg <literal>/app/page</literal>). During testing it was discovered
+        that Internet Explorer 6 Service Pack 1 has a bug whereby it does not
+        respond correctly to a redirection instruction which also changes the
+        port to use. Accordingly, absolute URLs are used in conjunction with
+        bug detection logic in the <literal>PortResolverImpl</literal> that is
+        wired up by default to many Spring Security beans. Please refer to the
+        JavaDocs for <literal>PortResolverImpl</literal> for further
+        details.</para>
+    
+    <para>You should note that using a secure channel is recommended if
+        usernames and passwords are to be kept secure during the login
+        process. If you do decide to use
+        <literal>ChannelProcessingFilter</literal> with form-based login,
+        please ensure that your login page is set to
+        <literal>REQUIRES_SECURE_CHANNEL</literal>, and that the
+        <literal>AuthenticationProcessingFilterEntryPoint.forceHttps</literal>
+        property is <literal>true</literal>.</para>
+</sect1>
+
+<sect1 id="channel-security-conclusion">
+    <title>Conclusion</title>
+    
+    <para>Once configured, using the channel security filter is very easy.
+        Simply request pages without regard to the protocol (ie HTTP or HTTPS)
+        or port (eg 80, 8080, 443, 8443 etc). Obviously you'll still need a
+        way of making the initial request (probably via the
+        <literal>web.xml</literal> <literal>&lt;welcome-file&gt;</literal> or
+        a well-known home page URL), but once this is done the filter will
+        perform redirects as defined by your application context.</para>
+    
+    <para>You can also add your own <literal>ChannelProcessor</literal>
+        implementations to the <literal>ChannelDecisionManagerImpl</literal>.
+        For example, you might set a <literal>HttpSession</literal> attribute
+        when a human user is detected via a "enter the contents of this
+        graphic" procedure. Your <literal>ChannelProcessor</literal> would
+        respond to say <literal>REQUIRES_HUMAN_USER</literal> configuration
+        attributes and redirect to an appropriate entry point to start the
+        human user validation process if the <literal>HttpSession</literal>
+        attribute is not currently set.</para>
+    
+    <para>To decide whether a security check belongs in a
+        <literal>ChannelProcessor</literal> or an
+        <literal>AccessDecisionVoter</literal>, remember that the former is
+        designed to handle unauthenticated requests, whilst the latter is
+        designed to handle authenticated requests. The latter therefore has
+        access to the granted authorities of the authenticated principal. In
+        addition, problems detected by a <literal>ChannelProcessor</literal>
+        will generally cause an HTTP/HTTPS redirection so its requirements can
+        be met, whilst problems detected by an
+        <literal>AccessDecisionVoter</literal> will ultimately result in an
+        <literal>AccessDeniedException</literal> (depending on the governing
+        <literal>AccessDecisionManager</literal>).</para>
+</sect1>
+</chapter>

src/docbkx/common-auth-services.xml

@@ -0,0 +1,456 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="authentication-common-auth-services">
+  <title>Common Authentication Services</title>
+
+  <sect1 id="mechanisms-providers-entry-points">
+    <title>Mechanisms, Providers and Entry Points</title>
+
+    <para>If you're using Spring Security-provided authentication
+    approaches, you'll usually need to configure a web filter, together
+    with an <literal>AuthenticationProvider</literal> and
+    <literal>AuthenticationEntryPoint</literal>. In this section we are
+    going to explore an example application that needs to support both
+    form-based authentication (ie so a nice HTML page is presented to a
+    user for them to login) plus BASIC authentication (ie so a web service
+    or similar can access protected resources).</para>
+
+    <para>In the web.xml, this application will need a single Acegi
+    Security filter in order to use the FilterChainProxy. Nearly every
+    Spring Security application will have such an entry, and it looks like
+    this:</para>
+
+    <para><programlisting>&lt;filter&gt;
+&lt;filter-name&gt;Spring Security Filter Chain Proxy&lt;/filter-name&gt;
+&lt;filter-class&gt;org.springframework.security.util.FilterToBeanProxy&lt;/filter-class&gt;
+&lt;init-param&gt;
+&lt;param-name&gt;targetClass&lt;/param-name&gt;
+&lt;param-value&gt;org.springframework.security.util.FilterChainProxy&lt;/param-value&gt;
+&lt;/init-param&gt;
+&lt;/filter&gt;
+
+&lt;filter-mapping&gt;
+&lt;filter-name&gt;Spring Security Filter Chain Proxy&lt;/filter-name&gt;
+&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+&lt;/filter-mapping&gt;</programlisting></para>
+
+    <para>The above declarations will cause every web request to be passed
+    through to Spring Security's FilterChainProxy. As explained in the
+    filters section of this reference guide, the
+    <classname>FilterChainProxy</classname> is a generally-useful class
+    that enables web requests to be passed to different filters based on
+    the URL patterns. Those delegated filters are managed inside the
+    application context, so they can benefit from dependency injection.
+    Let's have a look at what the FilterChainProxy bean definition would
+    look like inside your application context:</para>
+
+    <para><programlisting>&lt;bean id="filterChainProxy"
+        class="org.springframework.security.util.FilterChainProxy"&gt;
+&lt;property name="filterInvocationDefinitionSource"&gt;
+&lt;value&gt;
+  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+  PATTERN_TYPE_APACHE_ANT
+  /**=httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,basicProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,anonymousProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor,switchUserProcessingFilter
+&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;</programlisting></para>
+
+    <para>Internally Spring Security will use a
+    <literal>PropertyEditor</literal> to convert the string presented in
+    the above XML fragment into a
+    <literal>FilterInvocationDefinitionSource</literal> object. What's
+    important to note at this stage is that a series of filters will be
+    run - in the order specified by the declaration - and each of those
+    filters are actually the <literal>&lt;bean id&gt;</literal> of another
+    bean inside the application context. So, in our case some extra beans
+    will also appear in the application context, and they'll be named
+    <literal>httpSessionContextIntegrationFilter</literal>,
+    <literal>logoutFilter</literal> and so on. The order that the filters
+    should appear is discussed in the filters section of the reference
+    guide - although they are correct in the above example.</para>
+
+    <para>In our example we have the
+    <literal>AuthenticationProcessingFilter</literal> and
+    <literal>BasicProcessingFilter</literal> being used. These are the
+    "authentication mechanisms" that respond to form-based authentication
+    and BASIC HTTP header-based authentication respectively (we discussed
+    the role of authentication mechanisms earlier in this reference
+    guide). If you weren't using form or BASIC authentication, neither of
+    these beans would be defined. You'd instead define filters applicable
+    to your desired authentication environment, such as
+    <literal>DigestProcessingFilter</literal> or
+    <literal>CasProcessingFilter</literal>. Refer to the individual
+    chapters of this part of the reference guide to learn how to configure
+    each of these authentication mechanisms.</para>
+
+    <para>Recall that
+    <literal>HttpSessionContextIntegrationFilter</literal> keeps the
+    contents of the <literal>SecurityContext</literal> between invocations
+    inside an HTTP session. This means the authentication mechanisms are
+    only used once, being when the principal initially tries to
+    authenticate. The rest of the time the authentication mechanisms sit
+    there and silently pass the request through to the next filter in the
+    chain. That is a practical requirement due to the fact that few
+    authentication approaches present credentials on each and every call
+    (BASIC authentication being a notable exception), but what happens if
+    a principal's account gets cancelled or disabled or otherwise changed
+    (eg an increase or decrease in <literal>GrantedAuthority[]</literal>s)
+    after the initial authentication step? Let's look at how that is
+    handled now.</para>
+
+    <para>The major authorization provider for secure objects has
+    previously been introduced as
+    <literal>AbstractSecurityInterceptor</literal>. This class needs to
+    have access to an <literal>AuthenticationManager</literal>. It also
+    has configurable settings to indicate whether an
+    <literal>Authentication</literal> object should be re-authenticated on
+    each secure object invocation. By default it just accepts any
+    <literal>Authentication</literal> inside the
+    <literal>SecurityContextHolder</literal> is authenticated if
+    <literal>Authentication.isAuthenticated()</literal> returns true. This
+    is great for performance, but not ideal if you want to ensure
+    up-to-the-moment authentication validity. For such cases you'll
+    probably want to set the
+    <literal>AbstractSecurityInterceptor.alwaysReauthenticate</literal>
+    property to true.</para>
+
+    <para>You might be asking yourself, "what's this
+    <literal>AuthenticationManager</literal>?". We haven't explored it
+    before, but we have discussed the concept of an
+    <literal>AuthenticationProvider</literal>. Quite simply, an
+    <interfacename>AuthenticationManager</interfacename> is responsible
+    for passing requests through a chain of AuthenticationProviders. It's
+    a little like the filter chain we discussed earlier, although there
+    are some differences. There is only one
+    <interfacename>AuthenticationManager</interfacename> implementation
+    shipped with Spring Security, so let's look at how it's configured for
+    the example we're using in this chapter:</para>
+
+    <para><programlisting>&lt;bean id="authenticationManager"
+        class="org.springframework.security.providers.ProviderManager"&gt;
+&lt;property name="providers"&gt;
+&lt;list&gt;
+  &lt;ref local="daoAuthenticationProvider"/&gt;
+  &lt;ref local="anonymousAuthenticationProvider"/&gt;
+  &lt;ref local="rememberMeAuthenticationProvider"/&gt;
+&lt;/list&gt;
+&lt;/property&gt;
+&lt;/bean&gt;</programlisting></para>
+
+    <para>It's probably worth mentioning at this point that your
+    authentication mechanisms (which are usually filters) are also
+    injected with a reference to the
+    <literal>AuthenticationManager</literal>. So both
+    <literal>AbstractSecurityInterceptor</literal> as well as the
+    authentication mechanisms will use the above
+    <literal>ProviderManager</literal> to poll a list of
+    <literal>AuthenticationProvider</literal>s.</para>
+
+    <para>In our example we have three providers. They are tried in the
+    order shown (which is implied by the use of a <literal>List</literal>
+    instead of a <literal>Set</literal>), with each provider able to
+    attempt authentication, or skip authentication by simply returning
+    <literal>null</literal>. If all implementations return null, the
+    <literal>ProviderManager</literal> will throw a suitable exception. If
+    you're interested in learning more about chaining providers, please
+    refer to the <literal>ProviderManager</literal> JavaDocs.</para>
+
+    <para>The providers to use will sometimes be interchangeable with the
+    authentication mechanisms, whilst at other times they will depend on a
+    specific authentication mechanism. For example, the
+    <literal>DaoAuthenticationProvider</literal> just needs a string-based
+    username and password. Various authentication mechanisms result in the
+    collection of a string-based username and password, including (but not
+    limited to) BASIC and form authentication. Equally, some
+    authentication mechanisms create an authentication request object
+    which can only be interpreted by a single type of
+    <literal>AuthenticationProvider</literal>. An example of this
+    one-to-one mapping would be JA-SIG CAS, which uses the notion of a
+    service ticket which can therefore only be authenticated by
+    <literal>CasAuthenticationProvider</literal>. A further example of a
+    one-to-one mapping would be the LDAP authentication mechanism, which
+    can only be processed an the
+    <literal>LdapAuthenticationProvider</literal>. The specifics of such
+    relationships are detailed in the JavaDocs for each class, plus the
+    authentication approach-specific chapters of this reference guide. You
+    need not be terribly concerned about this implementation detail,
+    because if you forget to register a suitable provider, you'll simply
+    receive a <literal>ProviderNotFoundException</literal> when an attempt
+    to authenticate is made.</para>
+
+    <para>After configuring the correct authentication mechanisms in the
+    <literal>FilterChainProxy</literal>, and ensuring that a corresponding
+    <literal>AuthenticationProvider</literal> is registered in the
+    <literal>ProviderManager</literal>, your last step is to configure an
+    <literal>AuthenticationEntryPoint</literal>. Recall that earlier we
+    discussed the role of <literal>ExceptionTranslationFilter</literal>,
+    which is used when HTTP-based requests should receive back an HTTP
+    header or HTTP redirect in order to start authentication. Continuing
+    on with our earlier example:</para>
+
+    <para><programlisting>&lt;bean id="exceptionTranslationFilter"
+        class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
+&lt;property name="authenticationEntryPoint"&gt;&lt;ref local="authenticationProcessingFilterEntryPoint"/&gt;&lt;/property&gt;
+&lt;property name="accessDeniedHandler"&gt;
+&lt;bean class="org.springframework.security.ui.AccessDeniedHandlerImpl"&gt;
+  &lt;property name="errorPage" value="/accessDenied.jsp"/&gt;
+&lt;/bean&gt;
+&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="authenticationProcessingFilterEntryPoint"
+        class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint"&gt;
+&lt;property name="loginFormUrl"&gt;&lt;value&gt;/acegilogin.jsp&lt;/value&gt;&lt;/property&gt;
+&lt;property name="forceHttps"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;</programlisting></para>
+
+    <para>Notice that the <literal>ExceptionTranslationFilter</literal>
+    requires two collaborators. The first,
+    <literal>AccessDeniedHandlerImpl</literal>, uses a
+    <literal>RequestDispatcher</literal> forward to display the specified
+    access denied error page. We use a forward so that the
+    <literal>SecurityContextHolder</literal> still contains details of the
+    principal, which may be useful for display to the user (in old
+    releases of Spring Security we relied upon the servlet container to
+    handle a 403 error message, which lacked this useful contextual
+    information). <literal>AccessDeniedHandlerImpl</literal> will also set
+    the HTTP header to 403, which is the official error code to indicate
+    access denied. In the case of the
+    <literal>AuthentionEntryPoint</literal>, here we're setting what
+    action we would like taken when an unauthenticated principal attempts
+    to perform a protected operation. Because in our example we're going
+    to be using form-based authentication, we specify
+    <literal>AuthenticationProcessinFilterEntryPoint</literal> and the URL
+    of the login page. Your application will usually only have one entry
+    point, and most authentication approaches define their own specific
+    <literal>AuthenticationEntryPoint</literal>. Details of which entry
+    point to use for each authentication approach is discussed in the
+    authentication approach-specific chapters of this reference
+    guide.</para>
+  </sect1>
+
+  <sect1 id="userdetails-and-associated-types">
+    <title>UserDetails and Associated Types</title>
+
+    <para>As mentioned in the first part of the reference guide, most
+    authentication providers take advantage of the
+    <literal>UserDetails</literal> and
+    <literal>UserDetailsService</literal> interfaces. The contract for
+    this latter interface consists of a single method:</para>
+
+    <para><programlisting>public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException;</programlisting></para>
+
+    <para>The returned <literal>UserDetails</literal> is an interface that
+    provides getters that guarantee non-null provision of basic
+    authentication information such as the username, password, granted
+    authorities and whether the user is enabled or disabled. Most
+    authentication providers will use a
+    <literal>UserDetailsService</literal>, even if the username and
+    password are not actually used as part of the authentication decision.
+    Generally such provider will be using the returned
+    <literal>UserDetails</literal> object just for its
+    <literal>GrantedAuthority[]</literal> information, because some other
+    system (like LDAP or X509 or CAS etc) has undertaken the
+    responsibility of actually validating the credentials.</para>
+
+    <para>A single concrete implementation of
+    <literal>UserDetails</literal> is provided with Spring Security, being
+    the <literal>User</literal> class. Spring Security users will need to
+    decide when writing their <literal>UserDetailsService</literal> what
+    concrete <literal>UserDetails</literal> class to return. In most cases
+    <literal>User</literal> will be used directly or subclassed, although
+    special circumstances (such as object relational mappers) may require
+    users to write their own <literal>UserDetails</literal> implementation
+    from scratch. This is not such an unusual situation, and users should
+    not hesitate to simply return their normal domain object that
+    represents a user of the system. This is especially common given that
+    <literal>UserDetails</literal> is often used to store additional
+    principal-related properties (such as their telephone number and email
+    address), so that they can be easily used by web views.</para>
+
+    <para>Given <literal>UserDetailsService</literal> is so simple to
+    implement, it should be easy for users to retrieve authentication
+    information using a persistence strategy of their choice. Having said
+    that, Spring Security does include a couple of useful base
+    implementations, which we'll look at below.</para>
+
+    <sect2 id="in-memory-service">
+      <title>In-Memory Authentication</title>
+
+      <para>Whilst it is easy to use create a custom
+      <literal>UserDetailsService</literal> implementation that extracts
+      information from a persistence engine of choice, many applications
+      do not require such complexity. This is particularly true if you're
+      undertaking a rapid prototype or just starting integrating Spring
+      Security, when you don't really want to spend time configuring
+      databases or writing <literal>UserDetailsService</literal>
+      implementations. For this sort of situation, a simple option is to
+      configure the <literal>InMemoryDaoImpl</literal>
+      implementation:</para>
+
+      <para><programlisting>&lt;bean id="inMemoryDaoImpl"
+          class="org.springframework.security.userdetails.memory.InMemoryDaoImpl"&gt;
+&lt;property name="userMap"&gt;
+&lt;value&gt;
+  rod=koala,ROLE_TELLER,ROLE_SUPERVISOR
+  dianne=emu,ROLE_TELLER
+  scott=wombat,ROLE_TELLER
+  peter=opal,disabled,ROLE_TELLER
+&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting></para>
+
+      <para>In the above example, the <literal>userMap</literal> property
+      contains each of the usernames, passwords, a list of granted
+      authorities and an optional enabled/disabled keyword. Commas are
+      used to delimit each token. The username must appear to the left of
+      the equals sign, and the password must be the first token to the
+      right of the equals sign. The <literal>enabled</literal> and
+      <literal>disabled</literal> keywords (case insensitive) may appear
+      in the second or any subsequent token. Any remaining tokens are
+      treated as granted authorities, which are created as
+      <literal>GrantedAuthorityImpl</literal> objects (this is just for
+      your reference - most applications don't need custom
+      <literal>GrantedAuthority</literal> implementations, so using the
+      default implementation in this manner is just fine). Note that if a
+      user has no password and/or no granted authorities, the user will
+      not be created in the in-memory authentication repository.</para>
+
+      <para><literal>InMemoryDaoImpl</literal> also offers a
+      <literal>setUserProperties(Properties)</literal> method, which
+      allows you to externalise the
+      <literal>java.util.Properties</literal> in another Spring configured
+      bean or an external properties file. You might like to use Spring's
+      <literal>PropertiesFactoryBean</literal>, which is useful for
+      loading such external properties files. This setter might prove
+      useful for simple applications that have a larger number of users,
+      or deployment-time configuration changes, but do not wish to use a
+      full database for handling authentication details.</para>
+    </sect2>
+
+    <sect2 id="jdbc-service">
+      <title>JDBC Authentication</title>
+
+      <para>Spring Security also includes a
+      <literal>UserDetailsService</literal> that can obtain authentication
+      information from a JDBC data source. Internally Spring JDBC is used,
+      so it avoids the complexity of a fully-featured object relational
+      mapper (ORM) just to store user details. If your application does
+      use an ORM tool, you might prefer to write a custom
+      <literal>UserDetailsService</literal> to reuse the mapping files
+      you've probably already created. Returning to
+      <literal>JdbcDaoImpl</literal>, an example configuration is shown
+      below:</para>
+
+      <para><programlisting>&lt;bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource"&gt;
+&lt;property name="driverClassName"&gt;&lt;value&gt;org.hsqldb.jdbcDriver&lt;/value&gt;&lt;/property&gt;
+&lt;property name="url"&gt;&lt;value&gt;jdbc:hsqldb:hsql://localhost:9001&lt;/value&gt;&lt;/property&gt;
+&lt;property name="username"&gt;&lt;value&gt;sa&lt;/value&gt;&lt;/property&gt;
+&lt;property name="password"&gt;&lt;value&gt;&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="jdbcDaoImpl" class="org.springframework.security.userdetails.jdbc.JdbcDaoImpl"&gt;
+&lt;property name="dataSource"&gt;&lt;ref bean="dataSource"/&gt;&lt;/property&gt;
+&lt;/bean&gt;        </programlisting></para>
+
+      <para>You can use different relational database management systems
+      by modifying the <literal>DriverManagerDataSource</literal> shown
+      above. You can also use a global data source obtained from JNDI, as
+      per normal Spring options. Irrespective of the database used and how
+      a <literal>DataSource</literal> is obtained, a standard schema must
+      be used as indicated in <literal>dbinit.txt</literal>. You can
+      download this file from the Spring Security web site.</para>
+
+      <para>If your default schema is unsuitable for your needs,
+      <literal>JdbcDaoImpl</literal> provides two properties that allow
+      customisation of the SQL statements. You may also subclass the
+      <literal>JdbcDaoImpl</literal> if further customisation is
+      necessary. Please refer to the JavaDocs for details, although please
+      note that the class is not intended for complex custom subclasses.
+      If you have complex needs (such as a special schema or would like a
+      certain <literal>UserDetails</literal> implementation returned),
+      you'd be better off writing your own
+      <literal>UserDetailsService</literal>. The base implementation
+      provided with Spring Security is intended for typical situations,
+      and does not offer infinite configuration flexibility.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 id="concurrent-sessions">
+    <title>Concurrent Session Handling</title>
+
+    <para>Spring Security is able to prevent a principal from concurrently
+    authenticating to the same application more than a specified number of
+    times. Many ISVs take advantage of this to enforce licensing, whilst
+    network administrators like this feature because it helps prevent
+    people from sharing login names. You can, for example, stop user
+    "Batman" from logging onto the web application from two different
+    sessions.</para>
+
+    <para>To use concurrent session support, you'll need to add the
+    following to <literal>web.xml</literal>:</para>
+
+    <para><programlisting>&lt;listener&gt;
+&lt;listener-class&gt;org.springframework.security.ui.session.HttpSessionEventPublisher&lt;/listener-class&gt;
+&lt;/listener&gt;        </programlisting></para>
+
+    <para>In addition, you will need to add the
+    <literal>org.springframework.security.concurrent.ConcurrentSessionFilter</literal>
+    to your <literal>FilterChainProxy</literal>. The
+    <classname>ConcurrentSessionFilter</classname> requires two
+    properties, <literal>sessionRegistry</literal>, which generally points
+    to an instance of <literal>SessionRegistryImpl</literal>, and
+    <literal>expiredUrl</literal>, which points to the page to display
+    when a session has expired.</para>
+
+    <para>The <literal>web.xml</literal>
+    <literal>HttpSessionEventPublisher</literal> causes an
+    <literal>ApplicationEvent</literal> to be published to the Spring
+    <literal>ApplicationContext</literal> every time a
+    <literal>HttpSession</literal> commences or terminates. This is
+    critical, as it allows the <literal>SessionRegistryImpl</literal> to
+    be notified when a session ends.</para>
+
+    <para>You will also need to wire up the
+    <literal>ConcurrentSessionControllerImpl</literal> and refer to it
+    from your <literal>ProviderManager</literal> bean:</para>
+
+    <para><programlisting>&lt;bean id="authenticationManager"
+        class="org.springframework.security.providers.ProviderManager"&gt;
+&lt;property name="providers"&gt;
+&lt;!-- your providers go here --&gt;
+&lt;/property&gt;
+&lt;property name="sessionController"&gt;&lt;ref bean="concurrentSessionController"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="concurrentSessionController"
+        class="org.springframework.security.concurrent.ConcurrentSessionControllerImpl"&gt;
+&lt;property name="maximumSessions"&gt;&lt;value&gt;1&lt;/value&gt;&lt;/property&gt;
+&lt;property name="sessionRegistry"&gt;&lt;ref local="sessionRegistry"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="sessionRegistry" class="org.springframework.security.concurrent.SessionRegistryImpl"/&gt;</programlisting></para>
+  </sect1>
+
+  <sect1 id="authentication-taglibs">
+    <title>Authentication Tag Libraries</title>
+
+    <para><literal>AuthenticationTag</literal> is used to simply output a
+    property of the current principal's
+    <literal>Authentication.getPrincipal()</literal> object to the web
+    page.</para>
+
+    <para>The following JSP fragment illustrates how to use the
+    <literal>AuthenticationTag</literal>:</para>
+
+    <para><programlisting>&lt;security:authentication operation="username"/&gt;</programlisting></para>
+
+    <para>This tag would cause the principal's name to be output. Here we
+    are assuming the <literal>Authentication.getPrincipal()</literal> is a
+    <literal>UserDetails</literal> object, which is generally the case
+    when using the typical
+    <literal>DaoAuthenticationProvider</literal>.</para>
+  </sect1>
+</chapter>

src/docbkx/community.xml

@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="community">
+<title>Community Support</title>
+
+<sect1 id="jira">
+    <title>Use JIRA for Issue Tracking</title>
+    
+    <para>Spring Security uses JIRA to manage bug reports and enhancement
+        requests. If you find a bug, please log a report using JIRA. Do not
+        log it on the support forum, mailing list or by emailing the project's
+        developers. Such approaches are ad-hoc and we prefer to manage bugs
+        using a more formal process.</para>
+    
+    <para>If possible, in your JIRA report please provide a JUnit test
+        that demonstrates any incorrect behaviour. Or, better yet, provide a
+        patch that corrects the issue. Similarly, enhancements are welcome to
+        be logged in JIRA, although we only accept commit enhancement requests
+        if you include corresponding unit tests. This is necessary to ensure
+        project test coverage is adequately maintained.</para>
+    
+    <para>You can access JIRA at <ulink
+        url="http://opensource.atlassian.com/projects/spring/secure/BrowseProject.jspa?id=10040"></ulink>.</para>
+</sect1>
+
+<sect1 id="becoming-involved">
+    <title>Becoming Involved</title>
+    
+    <para>We welcome you to become involved in Spring Security project.
+        There are many ways of contributing, including reading the mailing
+        list and responding to questions from other people, writing new code,
+        improving existing code, assisting with documentation, developing
+        samples or tutorials, or simply making suggestions.</para>
+    
+    <para>Please read our project policies web page that is available on
+        Spring Security home page. This explains the path to become a
+        committer, and the administration approaches we use within the
+        project.</para>
+</sect1>
+
+<sect1 id="further-info">
+    <title>Further Information</title>
+    
+    <para>Questions and comments on Spring Security are welcome. Please
+        use the Spring Community Forum web site at <ulink
+            url="http://forum.springframework.org"></ulink> for all support
+        issues. Remember to use JIRA for bug reports, as explained above.
+        Everyone is also welcome to join the Acegisecurity-developer mailing
+        list and participate in design discussions. It's also a good way of
+        finding out what's happening with regard to release timing, and the
+        traffic volume is quite light. Finally, our project home page (where
+        you can obtain the latest release of the project and convenient links
+        to Subversion, JIRA, mailing lists, forums etc) is at <ulink
+            url="http://acegisecurity.org"></ulink>.</para>
+</sect1>
+</chapter>

src/docbkx/container-adapters.xml

@@ -0,0 +1,453 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">  
+
+<chapter id="ca">
+  <title>Container Adapter Authentication</title>
+
+  <sect1 id="ca-overview">
+    <title>Overview</title>
+
+    <para>Very early versions of Spring Security exclusively used
+    Container Adapters for interfacing authentication with end users.
+    Whilst this worked well, it required considerable time to support
+    multiple container versions and the configuration itself was
+    relatively time-consuming for developers. For this reason the HTTP
+    Form Authentication and HTTP Basic Authentication approaches were
+    developed, and are today recommended for almost all
+    applications.</para>
+
+    <para>Container Adapters enable Spring Security to integrate directly
+    with the containers used to host end user applications. This
+    integration means that applications can continue to leverage the
+    authentication and authorization capabilities built into containers
+    (such as <literal>isUserInRole()</literal> and form-based or basic
+    authentication), whilst benefiting from the enhanced security
+    interception capabilities provided by Spring Security (it should be
+    noted that Spring Security also offers
+    <literal>ContextHolderAwareRequestWrapper</literal> to deliver
+    <literal>isUserInRole()</literal> and similar Servlet Specification
+    compatibility methods).</para>
+
+    <para>The integration between a container and Spring Security is
+    achieved through an adapter. The adapter provides a
+    container-compatible user authentication provider, and needs to return
+    a container-compatible user object.</para>
+
+    <para>The adapter is instantiated by the container and is defined in a
+    container-specific configuration file. The adapter then loads a Spring
+    application context which defines the normal authentication manager
+    settings, such as the authentication providers that can be used to
+    authenticate the request. The application context is usually named
+    <literal>acegisecurity.xml</literal> and is placed in a
+    container-specific location.</para>
+
+    <para>Spring Security currently supports Jetty, Catalina (Tomcat),
+    JBoss and Resin. Additional container adapters can easily be
+    written</para>
+  </sect1>
+
+  <sect1 id="ca-adapter">
+    <title>Adapter Authentication Provider</title>
+
+    <para>As is always the case, the container adapter generated
+    <literal>Authentication</literal> object still needs to be
+    authenticated by an <literal>AuthenticationManager</literal> when
+    requested to do so by the
+    <literal>AbstractSecurityInterceptor</literal>. The
+    <literal>AuthenticationManager</literal> needs to be certain the
+    adapter-provided <literal>Authentication</literal> object is valid and
+    was actually authenticated by a trusted adapter.</para>
+
+    <para>Adapters create <literal>Authentication</literal> objects which
+    are immutable and implement the <literal>AuthByAdapter</literal>
+    interface. These objects store the hash of a key that is defined by
+    the adapter. This allows the <literal>Authentication</literal> object
+    to be validated by the <literal>AuthByAdapterProvider</literal>. This
+    authentication provider is defined as follows:</para>
+
+    <para><programlisting>&lt;bean id="authByAdapterProvider"
+        class="org.springframework.security.adapters.AuthByAdapterProvider"&gt;
+&lt;property name="key"&gt;&lt;value&gt;my_password&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;       </programlisting></para>
+
+    <para>The key must match the key that is defined in the
+    container-specific configuration file that starts the adapter. The
+    <literal>AuthByAdapterProvider</literal> automatically accepts as
+    valid any <literal>AuthByAdapter</literal> implementation that returns
+    the expected hash of the key.</para>
+
+    <para>To reiterate, this means the adapter will perform the initial
+    authentication using providers such as
+    <literal>DaoAuthenticationProvider</literal>, returning an
+    <literal>AuthByAdapter</literal> instance that contains a hash code of
+    the key. Later, when an application calls a security interceptor
+    managed resource, the <literal>AuthByAdapter</literal> instance in the
+    <literal>SecurityContext</literal> in the
+    <literal>SecurityContextHolder</literal> will be tested by the
+    application's <literal>AuthByAdapterProvider</literal>. There is no
+    requirement for additional authentication providers such as
+    <literal>DaoAuthenticationProvider</literal> within the
+    application-specific application context, as the only type of
+    <literal>Authentication</literal> instance that will be presented by
+    the application is from the container adapter.</para>
+
+    <para>Classloader issues are frequent with containers and the use of
+    container adapters illustrates this further. Each container requires a
+    very specific configuration. The installation instructions are
+    provided below. Once installed, please take the time to try the sample
+    application to ensure your container adapter is properly
+    configured.</para>
+
+    <para>When using container adapters with the
+    <literal>DaoAuthenticationProvider</literal>, ensure you set its
+    <literal>forcePrincipalAsString</literal> property to
+    <literal>true</literal>.</para>
+  </sect1>
+
+  <sect1 id="ca-jetty">
+    <title>Jetty</title>
+
+    <para>The following was tested with Jetty 4.2.18.</para>
+
+    <para><literal>$JETTY_HOME</literal> refers to the root of your Jetty
+    installation.</para>
+
+    <para>Edit your <literal>$JETTY_HOME/etc/jetty.xml</literal> file so
+    the <literal>&lt;Configure class&gt;</literal> section has a new
+    <literal>addRealm</literal> call:</para>
+
+    <para><programlisting>
+&lt;Call name="addRealm"&gt;
+&lt;Arg&gt;
+  &lt;New class="org.springframework.security.adapters.jetty.JettySpringSecurityUserRealm"&gt;
+    &lt;Arg&gt;Spring Powered Realm&lt;/Arg&gt;
+    &lt;Arg&gt;my_password&lt;/Arg&gt;
+    &lt;Arg&gt;etc/acegisecurity.xml&lt;/Arg&gt;
+  &lt;/New&gt;
+&lt;/Arg&gt;
+&lt;/Call&gt;
+
+    </programlisting></para>
+
+    <para>Copy <literal>acegisecurity.xml</literal> into
+    <literal>$JETTY_HOME/etc</literal>.</para>
+
+    <para>Copy the following files into
+    <literal>$JETTY_HOME/ext</literal>:<itemizedlist>
+        <listitem>
+          <para><literal>aopalliance.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>commons-logging.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>spring.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>acegi-security-jetty-XX.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>commons-codec.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>burlap.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>hessian.jar</literal></para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>None of the above JAR files (or
+    <literal>acegi-security-XX.jar</literal>) should be in your
+    application's <literal>WEB-INF/lib</literal>. The realm name indicated
+    in your <literal>web.xml</literal> does matter with Jetty. The
+    <literal>web.xml</literal> must express the same
+    <literal>&lt;realm-name&gt;</literal> as your
+    <literal>jetty.xml</literal> (in the example above, "Spring Powered
+    Realm").</para>
+  </sect1>
+
+  <sect1 id="ca-jboss">
+    <title>JBoss</title>
+
+    <para>The following was tested with JBoss 3.2.6.</para>
+
+    <para><literal>$JBOSS_HOME</literal> refers to the root of your JBoss
+    installation.</para>
+
+    <para>There are two different ways of making spring context available
+    to the Jboss integration classes.</para>
+
+    <para>The first approach is by editing your
+    <literal>$JBOSS_HOME/server/your_config/conf/login-config.xml</literal>
+    file so that it contains a new entry under the
+    <literal>&lt;Policy&gt;</literal> section:</para>
+
+    <para><programlisting>
+&lt;application-policy name = "SpringPoweredRealm"&gt;
+&lt;authentication&gt;
+  &lt;login-module code = "org.springframework.security.adapters.jboss.JbossSpringSecurityLoginModule"
+        flag = "required"&gt;
+    &lt;module-option name = "appContextLocation"&gt;acegisecurity.xml&lt;/module-option&gt;
+    &lt;module-option name = "key"&gt;my_password&lt;/module-option&gt;
+ &lt;/login-module&gt;
+&lt;/authentication&gt;
+&lt;/application-policy&gt;
+
+    </programlisting></para>
+
+    <para>Copy <literal>acegisecurity.xml</literal> into
+    <literal>$JBOSS_HOME/server/your_config/conf</literal>.</para>
+
+    <para>In this configuration <literal>acegisecurity.xml</literal>
+    contains the spring context definition including all the
+    authentication manager beans. You have to bear in mind though, that
+    <literal>SecurityContext</literal> is created and destroyed on each
+    login request, so the login operation might become costly.
+    Alternatively, the second approach is to use Spring singleton
+    capabilities through
+    <literal>org.springframework.beans.factory.access.SingletonBeanFactoryLocator</literal>.
+    The required configuration for this approach is:</para>
+
+    <para><programlisting>
+&lt;application-policy name = "SpringPoweredRealm"&gt;
+&lt;authentication&gt;
+  &lt;login-module code = "org.springframework.security.adapters.jboss.JbossSpringSecurityLoginModule"
+        flag = "required"&gt;
+    &lt;module-option name = "singletonId"&gt;springRealm&lt;/module-option&gt;
+    &lt;module-option name = "key"&gt;my_password&lt;/module-option&gt;
+    &lt;module-option name = "authenticationManager"&gt;authenticationManager&lt;/module-option&gt;
+ &lt;/login-module&gt;
+&lt;/authentication&gt;
+&lt;/application-policy&gt;
+
+    </programlisting></para>
+
+    <para>In the above code fragment,
+    <literal>authenticationManager</literal> is a helper property that
+    defines the expected name of the
+    <literal>AuthenticationManager</literal> in case you have several
+    defined in the IoC container. The <literal>singletonId</literal>
+    property references a bean defined in a
+    <literal>beanRefFactory.xml</literal> file. This file needs to be
+    available from anywhere on the JBoss classpath, including
+    <literal>$JBOSS_HOME/server/your_config/conf</literal>. The
+    <literal>beanRefFactory.xml</literal> contains the following
+    declaration:</para>
+
+    <para><programlisting>
+&lt;beans&gt;
+&lt;bean id="springRealm" singleton="true" lazy-init="true" class="org.springframework.context.support.ClassPathXmlApplicationContext"&gt;
+&lt;constructor-arg&gt;
+  &lt;list&gt;
+    &lt;value&gt;acegisecurity.xml&lt;/value&gt;
+  &lt;/list&gt;
+&lt;/constructor-arg&gt;
+&lt;/bean&gt;
+&lt;/beans&gt;
+
+    </programlisting></para>
+
+    <para>Finally, irrespective of the configuration approach you need to
+    copy the following files into
+    <literal>$JBOSS_HOME/server/your_config/lib</literal>:<itemizedlist>
+        <listitem>
+          <para><literal>aopalliance.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>spring.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>acegi-security-jboss-XX.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>commons-codec.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>burlap.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>hessian.jar</literal></para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>None of the above JAR files (or
+    <literal>acegi-security-XX.jar</literal>) should be in your
+    application's <literal>WEB-INF/lib</literal>. The realm name indicated
+    in your <literal>web.xml</literal> does not matter with JBoss.
+    However, your web application's
+    <literal>WEB-INF/jboss-web.xml</literal> must express the same
+    <literal>&lt;security-domain&gt;</literal> as your
+    <literal>login-config.xml</literal>. For example, to match the above
+    example, your <literal>jboss-web.xml</literal> would look like
+    this:</para>
+
+    <para><programlisting>
+&lt;jboss-web&gt;
+&lt;security-domain&gt;java:/jaas/SpringPoweredRealm&lt;/security-domain&gt;
+&lt;/jboss-web&gt;</programlisting></para>
+
+    <para>JBoss is a widely-used container adapter (mostly due to the need
+    to support legacy EJBs), so please let us know if you have any
+    difficulties.</para>
+  </sect1>
+
+  <sect1 id="ca-resin">
+    <title>Resin</title>
+
+    <para>The following was tested with Resin 3.0.6.</para>
+
+    <para><literal>$RESIN_HOME</literal> refers to the root of your Resin
+    installation.</para>
+
+    <para>Resin provides several ways to support the container adapter. In
+    the instructions below we have elected to maximise consistency with
+    other container adapter configurations. This will allow Resin users to
+    simply deploy the sample application and confirm correct
+    configuration. Developers comfortable with Resin are naturally able to
+    use its capabilities to package the JARs with the web application
+    itself, and/or support single sign-on.</para>
+
+    <para>Copy the following files into
+    <literal>$RESIN_HOME/lib</literal>:<itemizedlist>
+        <listitem>
+          <para><literal>aopalliance.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>commons-logging.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>spring.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>acegi-security-resin-XX.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>commons-codec.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>burlap.jar</literal></para>
+        </listitem>
+
+        <listitem>
+          <para><literal>hessian.jar</literal></para>
+        </listitem>
+      </itemizedlist></para>
+
+    <para>Unlike the container-wide <literal>acegisecurity.xml</literal>
+    files used by other container adapters, each Resin web application
+    will contain its own
+    <literal>WEB-INF/resin-acegisecurity.xml</literal> file. Each web
+    application will also contain a <literal>resin-web.xml</literal> file
+    which Resin uses to start the container adapter:</para>
+
+    <para><programlisting>
+&lt;web-app&gt;
+&lt;authenticator&gt;
+&lt;type&gt;org.springframework.security.adapters.resin.ResinAcegiAuthenticator&lt;/type&gt;
+&lt;init&gt;
+  &lt;app-context-location&gt;WEB-INF/resin-acegisecurity.xml&lt;/app-context-location&gt;
+  &lt;key&gt;my_password&lt;/key&gt;
+&lt;/init&gt;
+&lt;/authenticator&gt;
+&lt;/web-app&gt;
+
+    </programlisting></para>
+
+    <para>With the basic configuration provided above, none of the JAR
+    files listed (or <literal>acegi-security-XX.jar</literal>) should be
+    in your application's <literal>WEB-INF/lib</literal>. The realm name
+    indicated in your <literal>web.xml</literal> does not matter with
+    Resin, as the relevant authentication class is indicated by the
+    <literal>&lt;authenticator&gt;</literal> setting</para>
+  </sect1>
+
+  <sect1 id="ca-tomcat">
+    <title>Tomcat</title>
+
+    <para>The following was tested with Jakarta Tomcat 4.1.30 and
+    5.0.19.</para>
+
+    <para><literal>$CATALINA_HOME</literal> refers to the root of your
+    Catalina (Tomcat) installation.</para>
+
+    <para>Edit your <literal>$CATALINA_HOME/conf/server.xml</literal> file
+    so the <literal>&lt;Engine&gt;</literal> section contains only one
+    active <literal>&lt;Realm&gt;</literal> entry. An example realm
+    entry:</para>
+
+    <para><programlisting>      &lt;Realm
+        className="org.springframework.security.adapters.catalina.CatalinaSpringSecurityUserRealm"
+        appContextLocation="conf/acegisecurity.xml"
+         key="my_password" /&gt;</programlisting></para>
+
+    <para>Be sure to remove any other <literal>&lt;Realm&gt;</literal>
+    entry from your <literal>&lt;Engine&gt;</literal> section.</para>
+
+    <para>Copy <literal>acegisecurity.xml</literal> into
+    <literal>$CATALINA_HOME/conf</literal>.</para>
+
+    <para>Copy <literal>spring-security-catalina-XX.jar</literal> into
+    <literal>$CATALINA_HOME/server/lib</literal>.</para>
+
+    <para>Copy the following files into
+    <literal>$CATALINA_HOME/common/lib</literal>:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><literal>aopalliance.jar</literal></para>
+      </listitem>
+
+      <listitem>
+        <para><literal>spring.jar</literal></para>
+      </listitem>
+
+      <listitem>
+        <para><literal>commons-codec.jar</literal></para>
+      </listitem>
+
+      <listitem>
+        <para><literal>burlap.jar</literal></para>
+      </listitem>
+
+      <listitem>
+        <para><literal>hessian.jar</literal></para>
+      </listitem>
+    </itemizedlist>
+
+    <para>None of the above JAR files (or
+    <literal>spring-security-XX.jar</literal>) should be in your
+    application's <literal>WEB-INF/lib</literal>. The realm name indicated
+    in your <literal>web.xml</literal> does not matter with
+    Catalina.</para>
+
+    <para>We have received reports of problems using this Container
+    Adapter with Mac OS X. A work-around is to use a script such as
+    follows:</para>
+
+    <para><programlisting>#!/bin/sh
+export CATALINA_HOME="/Library/Tomcat"
+export JAVA_HOME="/Library/Java/Home"
+cd /
+$CATALINA_HOME/bin/startup.sh</programlisting></para>
+
+    <para>Finally, restart Tomcat.</para>
+  </sect1>
+</chapter>

src/docbkx/dao-auth-provider.xml

@@ -0,0 +1,130 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="dao-provider">
+<title>DAO Authentication Provider</title>
+
+<sect1 id="dao-provider-overview">
+    <title>Overview</title>
+    
+    <para>Spring Security includes a production-quality
+        <literal>AuthenticationProvider</literal> implementation called
+        <literal>DaoAuthenticationProvider</literal>. This authentication
+        provider is compatible with all of the authentication mechanisms that
+        generate a <literal>UsernamePasswordAuthenticationToken</literal>, and
+        is probably the most commonly used provider in the framework. Like
+        most of the other authentication providers, the
+        DaoAuthenticationProvider leverages a UserDetailsService in order to
+        lookup the username, password and GrantedAuthority[]s. Unlike most of
+        the other authentication providers that leverage UserDetailsService,
+        this authentication provider actually requires the password to be
+        presented, and the provider will actually evaluate the validity or
+        otherwise of the password presented in an authentication request
+        object.</para>
+</sect1>
+
+<sect1 id="dao-provider-config">
+    <title>Configuration</title>
+    
+    <para>Aside from adding DaoAuthenticationProvider to your
+        ProviderManager list (as discussed at the start of this part of the
+        reference guide), and ensuring a suitable authentication mechanism is
+        configured to present a UsernamePasswordAuthenticationToken, the
+        configuration of the provider itself is rather simple:</para>
+    
+    <para><programlisting>&lt;bean id="daoAuthenticationProvider"
+        class="org.springframework.security.providers.dao.DaoAuthenticationProvider"&gt;
+        &lt;property name="userDetailsService"&gt;&lt;ref bean="inMemoryDaoImpl"/&gt;&lt;/property&gt;
+        &lt;property name="saltSource"&gt;&lt;ref bean="saltSource"/&gt;&lt;/property&gt;
+        &lt;property name="passwordEncoder"&gt;&lt;ref bean="passwordEncoder"/&gt;&lt;/property&gt;
+        &lt;/bean&gt;        </programlisting></para>
+    
+    <para>The <literal>PasswordEncoder</literal> and
+        <literal>SaltSource</literal> are optional. A
+        <literal>PasswordEncoder</literal> provides encoding and decoding of
+        passwords presented in the <literal>UserDetails</literal> object that
+        is returned from the configured <literal>UserDetailsService</literal>.
+        A <literal>SaltSource</literal> enables the passwords to be populated
+        with a "salt", which enhances the security of the passwords in the
+        authentication repository. <literal>PasswordEncoder</literal>
+        implementations are provided with Spring Security covering MD5, SHA
+        and cleartext encodings. Two <literal>SaltSource</literal>
+        implementations are also provided:
+        <literal>SystemWideSaltSource</literal> which encodes all passwords
+        with the same salt, and <literal>ReflectionSaltSource</literal>, which
+        inspects a given property of the returned
+        <literal>UserDetails</literal> object to obtain the salt. Please refer
+        to the JavaDocs for further details on these optional features.</para>
+    
+    <para>In addition to the properties above, the
+        <literal>DaoAuthenticationProvider</literal> supports optional caching
+        of <literal>UserDetails</literal> objects. The
+        <literal>UserCache</literal> interface enables the
+        <literal>DaoAuthenticationProvider</literal> to place a
+        <literal>UserDetails</literal> object into the cache, and retrieve it
+        from the cache upon subsequent authentication attempts for the same
+        username. By default the <literal>DaoAuthenticationProvider</literal>
+        uses the <literal>NullUserCache</literal>, which performs no caching.
+        A usable caching implementation is also provided,
+        <literal>EhCacheBasedUserCache</literal>, which is configured as
+        follows:</para>
+    
+    <para><programlisting>&lt;bean id="daoAuthenticationProvider"
+        class="org.springframework.security.providers.dao.DaoAuthenticationProvider"&gt;
+        &lt;property name="userDetailsService"&gt;&lt;ref bean="userDetailsService"/&gt;&lt;/property&gt;
+        &lt;property name="userCache"&gt;&lt;ref bean="userCache"/&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean"&gt;
+        &lt;property name="configLocation"&gt;
+        &lt;value&gt;classpath:/ehcache-failsafe.xml&lt;/value&gt;
+        &lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="userCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean"&gt;
+        &lt;property name="cacheManager"&gt;
+        &lt;ref local="cacheManager"/&gt;
+        &lt;/property&gt;
+        &lt;property name="cacheName"&gt;
+        &lt;value&gt;userCache&lt;/value&gt;
+        &lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="userCache" class="org.springframework.security.providers.dao.cache.EhCacheBasedUserCache"&gt;
+        &lt;property name="cache"&gt;&lt;ref local="userCacheBackend"/&gt;&lt;/property&gt;
+        &lt;/bean&gt;        </programlisting></para>
+    
+    <para>All Spring Security EH-CACHE implementations (including
+        <literal>EhCacheBasedUserCache</literal>) require an EH-CACHE
+        <literal>Cache</literal> object. The <literal>Cache</literal> object
+        can be obtained from wherever you like, although we recommend you use
+        Spring's factory classes as shown in the above configuration. If using
+        Spring's factory classes, please refer to the Spring documentation for
+        further details on how to optimise the cache storage location, memory
+        usage, eviction policies, timeouts etc.</para>
+    
+    <para>A design decision was made not to support account locking in the
+        <literal>DaoAuthenticationProvider</literal>, as doing so would have
+        increased the complexity of the <literal>UserDetailsService</literal>
+        interface. For instance, a method would be required to increase the
+        count of unsuccessful authentication attempts. Such functionality
+        could be easily provided by leveraging the application event
+        publishing features discussed below.</para>
+    
+    <para><literal>DaoAuthenticationProvider</literal> returns an
+        <literal>Authentication</literal> object which in turn has its
+        <literal>principal</literal> property set. The principal will be
+        either a <literal>String</literal> (which is essentially the username)
+        or a <literal>UserDetails</literal> object (which was looked up from
+        the <literal>UserDetailsService</literal>). By default the
+        <literal>UserDetails</literal> is returned, as this enables
+        applications to add extra properties potentially of use in
+        applications, such as the user's full name, email address etc. If
+        using container adapters, or if your applications were written to
+        operate with <literal>String</literal>s (as was the case for releases
+        prior to Spring Security 0.6), you should set the
+        <literal>DaoAuthenticationProvider.forcePrincipalAsString</literal>
+        property to <literal>true</literal> in your application context</para>
+</sect1>
+</chapter>

src/docbkx/digest-authentication.xml

@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">                         
+
+<chapter id="digest">
+    <title>Digest Authentication</title>
+    
+    <sect1 id="digest-overview">
+        <title>Overview</title>
+        
+        <para>Spring Security provides a
+            <literal>DigestProcessingFilter</literal> which is capable of
+            processing digest authentication credentials presented in HTTP
+            headers. Digest Authentication attempts to solve many of the
+            weaknesses of Basic authentication, specifically by ensuring
+            credentials are never sent in clear text across the wire. Many user
+            agents support Digest Authentication, including FireFox and Internet
+            Explorer. The standard governing HTTP Digest Authentication is defined
+            by RFC 2617, which updates an earlier version of the Digest
+            Authentication standard prescribed by RFC 2069. Most user agents
+            implement RFC 2617. Spring Security
+            <literal>DigestProcessingFilter</literal> is compatible with the
+            "<literal>auth</literal>" quality of protection
+            (<literal>qop</literal>) prescribed by RFC 2617, which also provides
+            backward compatibility with RFC 2069. Digest Authentication is a
+            highly attractive option if you need to use unencrypted HTTP (ie no
+            TLS/HTTPS) and wish to maximise security of the authentication
+            process. Indeed Digest Authentication is a mandatory requirement for
+            the WebDAV protocol, as noted by RFC 2518 Section 17.1, so we should
+            expect to see it increasingly deployed and replacing Basic
+            Authentication.</para>
+        
+        <para>Digest Authentication is definitely the most secure choice
+            between Form Authentication, Basic Authentication and Digest
+            Authentication, although extra security also means more complex user
+            agent implementations. Central to Digest Authentication is a "nonce".
+            This is a value the server generates. Spring Security's nonce adopts
+            the following format:</para>
+        
+        <para><programlisting>base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key))
+            
+            expirationTime:   The date and time when the nonce expires, expressed in milliseconds
+            key:              A private key to prevent modification of the nonce token
+        </programlisting></para>
+        
+        <para>The <literal>DigestProcessingFilterEntryPoint</literal> has a
+            property specifying the <literal>key</literal> used for generating the
+            nonce tokens, along with a <literal>nonceValiditySeconds</literal>
+            property for determining the expiration time (default 300, which
+            equals five minutes). Whist ever the nonce is valid, the digest is
+            computed by concatenating various strings including the username,
+            password, nonce, URI being requested, a client-generated nonce (merely
+            a random value which the user agent generates each request), the realm
+            name etc, then performing an MD5 hash. Both the server and user agent
+            perform this digest computation, resulting in different hash codes if
+            they disagree on an included value (eg password). In Spring Security
+            implementation, if the server-generated nonce has merely expired (but
+            the digest was otherwise valid), the
+            <literal>DigestProcessingFilterEntryPoint</literal> will send a
+            <literal>"stale=true"</literal> header. This tells the user agent
+            there is no need to disturb the user (as the password and username etc
+            is correct), but simply to try again using a new nonce.</para>
+        
+        <para>An appropriate value for
+            <literal>DigestProcessingFilterEntryPoint</literal>'s
+            <literal>nonceValiditySeconds</literal> parameter will depend on your
+            application. Extremely secure applications should note that an
+            intercepted authentication header can be used to impersonate the
+            principal until the <literal>expirationTime</literal> contained in the
+            nonce is reached. This is the key principle when selecting an
+            appropriate setting, but it would be unusual for immensely secure
+            applications to not be running over TLS/HTTPS in the first
+            instance.</para>
+        
+        <para>Because of the more complex implementation of Digest
+            Authentication, there are often user agent issues. For example,
+            Internet Explorer fails to present an "<literal>opaque</literal>"
+            token on subsequent requests in the same session. Spring Security
+            filters therefore encapsulate all state information into the
+            "<literal>nonce</literal>" token instead. In our testing, Spring
+            Security implementation works reliably with FireFox and Internet
+            Explorer, correctly handling nonce timeouts etc.</para>
+    </sect1>
+    
+    <sect1 id="digest-config">
+        <title>Configuration</title>
+        
+        <para>Now that we've reviewed the theory, let's see how to use it. To
+            implement HTTP Digest Authentication, it is necessary to define
+            <literal>DigestProcessingFilter</literal> in the fitler chain. The
+            application context will need to define the
+            <literal>DigestProcessingFilter</literal> and its required
+            collaborators:</para>
+        
+        <para><programlisting>
+            &lt;bean id="digestProcessingFilter" class="org.springframework.security.ui.digestauth.DigestProcessingFilter"&gt;
+            &lt;property name="userDetailsService"&gt;&lt;ref local="jdbcDaoImpl"/&gt;&lt;/property&gt;
+            &lt;property name="authenticationEntryPoint"&gt;&lt;ref local="digestProcessingFilterEntryPoint"/&gt;&lt;/property&gt;
+            &lt;property name="userCache"&gt;&lt;ref local="userCache"/&gt;&lt;/property&gt;
+            &lt;/bean&gt;
+            
+            &lt;bean id="digestProcessingFilterEntryPoint"
+            class="org.springframework.security.ui.digestauth.DigestProcessingFilterEntryPoint"&gt;
+            &lt;property name="realmName"&gt;&lt;value&gt;Contacts Realm via Digest Authentication&lt;/value&gt;&lt;/property&gt;
+            &lt;property name="key"&gt;&lt;value&gt;acegi&lt;/value&gt;&lt;/property&gt;
+            &lt;property name="nonceValiditySeconds"&gt;&lt;value&gt;10&lt;/value&gt;&lt;/property&gt;
+            &lt;/bean&gt;
+            
+        </programlisting></para>
+        
+        <para>The configured <literal>UserDetailsService</literal> is needed
+            because <literal>DigestProcessingFilter</literal> must have direct
+            access to the clear text password of a user. Digest Authentication
+            will NOT work if you are using encoded passwords in your DAO. The DAO
+            collaborator, along with the <literal>UserCache</literal>, are
+            typically shared directly with a
+            <literal>DaoAuthenticationProvider</literal>. The
+            <literal>authenticationEntryPoint</literal> property must be
+            <literal>DigestProcessingFilterEntryPoint</literal>, so that
+            <literal>DigestProcessingFilter</literal> can obtain the correct
+            <literal>realmName</literal> and <literal>key</literal> for digest
+            calculations.</para>
+        
+        <para>Like <literal>BasicAuthenticationFilter</literal>, if
+            authentication is successful an <literal>Authentication</literal>
+            request token will be placed into the
+            <literal>SecurityContextHolder</literal>. If the authentication event
+            was successful, or authentication was not attempted because the HTTP
+            header did not contain a Digest Authentication request, the filter
+            chain will continue as normal. The only time the filter chain will be
+            interrupted is if authentication fails and the
+            <literal>AuthenticationEntryPoint</literal> is called, as discussed in
+            the previous paragraph.</para>
+        
+        <para>Digest Authentication's RFC offers a range of additional
+            features to further increase security. For example, the nonce can be
+            changed on every request. Despite this, Spring Security implementation
+            was designed to minimise the complexity of the implementation (and the
+            doubtless user agent incompatibilities that would emerge), and avoid
+            needing to store server-side state. You are invited to review RFC 2617
+            if you wish to explore these features in more detail. As far as we are
+            aware, Spring Security's implementation does comply with the minimum
+            standards of this RFC.</para>
+    </sect1>
+</chapter>

src/docbkx/domain-acls-old.xml

@@ -0,0 +1,478 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="domain-acls-old">
+  <title>Domain Object Security (old ACL module)</title>
+
+  <section id="domain-acls-overview-old">
+    <title>Overview</title>
+
+    <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
+    ACL module. The new ACL module is a significant rewrite of the
+    existing ACL module. The new module can be found under the
+    <literal>org.springframework.security.acls</literal> package, with the
+    old ACL module under
+    <literal>org.springframework.security.acl</literal>. We encourage
+    users to consider testing with the new ACL module and build
+    applications with it. The old ACL module should be considered
+    deprecated and may be removed from a future release.</para>
+
+    <para>Complex applications often will find the need to define access
+    permissions not simply at a web request or method invocation level.
+    Instead, security decisions need to comprise both who
+    (<literal>Authentication</literal>), where
+    (<literal>MethodInvocation</literal>) and what
+    (<literal>SomeDomainObject</literal>). In other words, authorization
+    decisions also need to consider the actual domain object instance
+    subject of a method invocation.</para>
+
+    <para>Imagine you're designing an application for a pet clinic. There
+    will be two main groups of users of your Spring-based application:
+    staff of the pet clinic, as well as the pet clinic's customers. The
+    staff will have access to all of the data, whilst your customers will
+    only be able to see their own customer records. To make it a little
+    more interesting, your customers can allow other users to see their
+    customer records, such as their "puppy preschool "mentor or president
+    of their local "Pony Club". Using Spring Security as the foundation,
+    you have several approaches that can be used:<orderedlist>
+        <listitem>
+          <para>Write your business methods to enforce the security. You
+          could consult a collection within the
+          <literal>Customer</literal> domain object instance to determine
+          which users have access. By using the
+          <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
+          you'll be able to access the <literal>Authentication</literal>
+          object.</para>
+        </listitem>
+
+        <listitem>
+          <para>Write an <literal>AccessDecisionVoter</literal> to enforce
+          the security from the <literal>GrantedAuthority[]</literal>s
+          stored in the <literal>Authentication</literal> object. This
+          would mean your <literal>AuthenticationManager</literal> would
+          need to populate the <literal>Authentication</literal> with
+          custom <literal>GrantedAuthority</literal>[]s representing each
+          of the <literal>Customer</literal> domain object instances the
+          principal has access to.</para>
+        </listitem>
+
+        <listitem>
+          <para>Write an <literal>AccessDecisionVoter</literal> to enforce
+          the security and open the target <literal>Customer</literal>
+          domain object directly. This would mean your voter needs access
+          to a DAO that allows it to retrieve the
+          <literal>Customer</literal> object. It would then access the
+          <literal>Customer</literal> object's collection of approved
+          users and make the appropriate decision.</para>
+        </listitem>
+      </orderedlist></para>
+
+    <para>Each one of these approaches is perfectly legitimate. However,
+    the first couples your authorization checking to your business code.
+    The main problems with this include the enhanced difficulty of unit
+    testing and the fact it would be more difficult to reuse the
+    <literal>Customer</literal> authorization logic elsewhere. Obtaining
+    the <literal>GrantedAuthority[]</literal>s from the
+    <literal>Authentication</literal> object is also fine, but will not
+    scale to large numbers of <literal>Customer</literal>s. If a user
+    might be able to access 5,000 <literal>Customer</literal>s (unlikely
+    in this case, but imagine if it were a popular vet for a large Pony
+    Club!) the amount of memory consumed and time required to construct
+    the <literal>Authentication</literal> object would be undesirable. The
+    final method, opening the <literal>Customer</literal> directly from
+    external code, is probably the best of the three. It achieves
+    separation of concerns, and doesn't misuse memory or CPU cycles, but
+    it is still inefficient in that both the
+    <literal>AccessDecisionVoter</literal> and the eventual business
+    method itself will perform a call to the DAO responsible for
+    retrieving the <literal>Customer</literal> object. Two accesses per
+    method invocation is clearly undesirable. In addition, with every
+    approach listed you'll need to write your own access control list
+    (ACL) persistence and business logic from scratch.</para>
+
+    <para>Fortunately, there is another alternative, which we'll talk
+    about below.</para>
+  </section>
+
+  <section id="domain-acls-basic-old">
+    <title>Basic ACL Package</title>
+
+    <para>Please note that our Basic ACL services are currently being
+    refactored. We expect release 1.1.0 will contain this new code.
+    Planned code is already in the Spring Security Subversion sandbox, so
+    please check there if you have a new application requiring ACLs or are
+    in the planning stages. The Basic ACL services will be deprecated from
+    release 1.1.0.</para>
+
+    <para>The <literal>org.springframework.security.acl</literal> package
+    is very simple, comprising only a handful of interfaces and a single
+    class, as shown in Figure 6. It provides the basic foundation for
+    access control list (ACL) lookups.</para>
+
+    <para><mediaobject>
+        <imageobject role="html">
+          <imagedata align="center" fileref="images/ACLSecurity.gif"
+                     format="GIF" />
+        </imageobject>
+
+        <caption>
+          <para>Figure 6: Access Control List Manager</para>
+        </caption>
+      </mediaobject></para>
+
+    <para>The central interface is <literal>AclManager</literal>, which is
+    defined by two methods:</para>
+
+    <para><programlisting>public AclEntry[] getAcls(java.lang.Object domainInstance);
+public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authentication);</programlisting></para>
+
+    <para><literal>AclManager</literal> is intended to be used as a
+    collaborator against your business objects, or, more desirably,
+    <literal>AccessDecisionVoter</literal>s. This means you use Spring's
+    normal <literal>ApplicationContext</literal> features to wire up your
+    <literal>AccessDecisionVoter</literal> (or business method) with an
+    <literal>AclManager</literal>. Consideration was given to placing the
+    ACL information in the <literal>ContextHolder</literal>, but it was
+    felt this would be inefficient both in terms of memory usage as well
+    as the time spent loading potentially unused ACL information. The
+    trade-off of needing to wire up a collaborator for those objects
+    requiring ACL information is rather minor, particularly in a
+    Spring-managed application.</para>
+
+    <para>The first method of the <literal>AclManager</literal> will
+    return all ACLs applying to the domain object instance passed to it.
+    The second method does the same, but only returns those ACLs which
+    apply to the passed <literal>Authentication</literal> object.</para>
+
+    <para>The <literal>AclEntry</literal> interface returned by
+    <literal>AclManager</literal> is merely a marker interface. You will
+    need to provide an implementation that reflects that ACL permissions
+    for your application.</para>
+
+    <para>Rounding out the
+    <literal>org.springframework.security.acl</literal> package is an
+    <literal>AclProviderManager</literal> class, with a corresponding
+    <literal>AclProvider</literal> interface.
+    <literal>AclProviderManager</literal> is a concrete implementation of
+    <literal>AclManager</literal>, which iterates through registered
+    <literal>AclProvider</literal>s. The first
+    <literal>AclProvider</literal> that indicates it can authoritatively
+    provide ACL information for the presented domain object instance will
+    be used. This is very similar to the
+    <literal>AuthenticationProvider</literal> interface used for
+    authentication.</para>
+
+    <para>With this background, let's now look at a usable ACL
+    implementation.</para>
+
+    <para>Spring Security includes a production-quality ACL provider
+    implementation, which is shown in Figure 7.</para>
+
+    <para><mediaobject>
+        <imageobject role="html">
+          <imagedata align="center" fileref="images/BasicAclProvider.gif"
+                     format="GIF" />
+        </imageobject>
+
+        <caption>
+          <para>Figure 7: Basic ACL Manager</para>
+        </caption>
+      </mediaobject></para>
+
+    <para>The implementation is based on integer masking, which is
+    commonly used for ACL permissions given its flexibility and speed.
+    Anyone who has used Unix's <literal>chmod</literal> command will know
+    all about this type of permission masking (eg <literal>chmod
+    777</literal>). You'll find the classes and interfaces for the integer
+    masking ACL package under
+    <literal>org.springframework.security.acl.basic</literal>.</para>
+
+    <para>Extending the <literal>AclEntry</literal> interface is a
+    <literal>BasicAclEntry</literal> interface, with the main methods
+    shown below:</para>
+
+    <para><programlisting>public AclObjectIdentity getAclObjectIdentity();
+public AclObjectIdentity getAclObjectParentIdentity();
+public int getMask();
+public java.lang.Object getRecipient();</programlisting></para>
+
+    <para>As shown, each <literal>BasicAclEntry</literal> has four main
+    properties. The <literal>mask</literal> is the integer that represents
+    the permissions granted to the <literal>recipient</literal>. The
+    <literal>aclObjectIdentity</literal> is able to identify the domain
+    object instance for which the ACL applies, and the
+    <literal>aclObjectParentIdentity</literal> optionally specifies the
+    parent of the domain object instance. Multiple
+    <literal>BasicAclEntry</literal>s usually exist against a single
+    domain object instance, and as suggested by the parent identity
+    property, permissions granted higher in the object hierarchy will
+    trickle down and be inherited (unless blocked by integer zero).</para>
+
+    <para><literal>BasicAclEntry</literal> implementations typically
+    provide convenience methods, such as
+    <literal>isReadAllowed()</literal>, to avoid application classes
+    needing to perform bit masking themselves. The
+    <literal>SimpleAclEntry</literal> and
+    <literal>AbstractBasicAclEntry</literal> demonstrate and provide much
+    of this bit masking logic.</para>
+
+    <para>The <literal>AclObjectIdentity</literal> itself is merely a
+    marker interface, so you need to provide implementations for your
+    domain objects. However, the package does include a
+    <literal>NamedEntityObjectIdentity</literal> implementation which will
+    suit many needs. The <literal>NamedEntityObjectIdentity</literal>
+    identifies a given domain object instance by the classname of the
+    instance and the identity of the instance. A
+    <literal>NamedEntityObjectIdentity</literal> can be constructed
+    manually (by calling the constructor and providing the classname and
+    identity <literal>String</literal>s), or by passing in any domain
+    object that contains a <literal>getId()</literal> method.</para>
+
+    <para>The actual <literal>AclProvider</literal> implementation is
+    named <literal>BasicAclProvider</literal>. It has adopted a similar
+    design to that used by the authentication-related
+    <literal>DaoAuthenticationProvder</literal>. Specifically, you define
+    a <literal>BasicAclDao</literal> against the provider, so different
+    ACL repository types can be accessed in a pluggable manner. The
+    <literal>BasicAclProvider</literal> also supports pluggable cache
+    providers (with Spring Security including an implementation that
+    fronts EH-CACHE).</para>
+
+    <para>The <literal>BasicAclDao</literal> interface is very simple to
+    implement:</para>
+
+    <para><programlisting>public BasicAclEntry[] getAcls(AclObjectIdentity aclObjectIdentity);</programlisting></para>
+
+    <para>A <literal>BasicAclDao</literal> implementation needs to
+    understand the presented <literal>AclObjectIdentity</literal> and how
+    it maps to a storage repository, find the relevant records, and create
+    appropriate <literal>BasicAclEntry</literal> objects and return
+    them.</para>
+
+    <para>Spring Security includes a single <literal>BasicAclDao</literal>
+    implementation called <literal>JdbcDaoImpl</literal>. As implied by
+    the name, <literal>JdbcDaoImpl</literal> accesses ACL information from
+    a JDBC database. There is also an extended version of this DAO,
+    <literal>JdbcExtendedDaoImpl</literal>, which provides CRUD operations
+    on the JDBC database, although we won't discuss these features here.
+    The default database schema and some sample data will aid in
+    understanding its function:</para>
+
+    <para><programlisting>CREATE TABLE acl_object_identity (
+ id IDENTITY NOT NULL,
+ object_identity VARCHAR_IGNORECASE(250) NOT NULL,
+ parent_object INTEGER,
+ acl_class VARCHAR_IGNORECASE(250) NOT NULL,
+ CONSTRAINT unique_object_identity UNIQUE(object_identity),
+ FOREIGN KEY (parent_object) REFERENCES acl_object_identity(id)
+);
+
+CREATE TABLE acl_permission (
+ id IDENTITY NOT NULL,
+ acl_object_identity INTEGER NOT NULL,
+ recipient VARCHAR_IGNORECASE(100) NOT NULL,
+ mask INTEGER NOT NULL,
+ CONSTRAINT unique_recipient UNIQUE(acl_object_identity, recipient),
+ FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity(id)
+);
+
+INSERT INTO acl_object_identity VALUES (1, 'corp.DomainObject:1', null,
+        'org.springframework.security.acl.basic.SimpleAclEntry');
+        INSERT INTO acl_object_identity VALUES (2, 'corp.DomainObject:2', 1,
+        'org.springframework.security.acl.basic.SimpleAclEntry');
+        INSERT INTO acl_object_identity VALUES (3, 'corp.DomainObject:3', 1,
+        'org.springframework.security.acl.basic.SimpleAclEntry');
+        INSERT INTO acl_object_identity VALUES (4, 'corp.DomainObject:4', 1,
+        'org.springframework.security.acl.basic.SimpleAclEntry');
+        INSERT INTO acl_object_identity VALUES (5, 'corp.DomainObject:5', 3,
+        'org.springframework.security.acl.basic.SimpleAclEntry');
+        INSERT INTO acl_object_identity VALUES (6, 'corp.DomainObject:6', 3,
+        'org.springframework.security.acl.basic.SimpleAclEntry');
+
+        INSERT INTO acl_permission VALUES (null, 1, 'ROLE_SUPERVISOR', 1);
+INSERT INTO acl_permission VALUES (null, 2, 'ROLE_SUPERVISOR', 0);
+INSERT INTO acl_permission VALUES (null, 2, 'rod', 2);
+INSERT INTO acl_permission VALUES (null, 3, 'scott', 14);
+INSERT INTO acl_permission VALUES (null, 6, 'scott', 1);</programlisting></para>
+
+    <para>As can be seen, database-specific constraints are used
+    extensively to ensure the integrity of the ACL information. If you
+    need to use a different database (Hypersonic SQL statements are shown
+    above), you should try to implement equivalent constraints. The
+    equivalent Oracle configuration is:</para>
+
+    <para><programlisting>CREATE TABLE ACL_OBJECT_IDENTITY (
+ ID number(19,0) not null,
+ OBJECT_IDENTITY varchar2(255) NOT NULL,
+ PARENT_OBJECT number(19,0),
+ ACL_CLASS varchar2(255) NOT NULL,
+ primary key (ID)
+);
+ALTER TABLE ACL_OBJECT_IDENTITY ADD CONTRAINT FK_PARENT_OBJECT foreign key (ID) references ACL_OBJECT_IDENTITY
+
+CREATE SEQUENCE ACL_OBJECT_IDENTITY_SEQ;
+
+CREATE OR REPLACE TRIGGER ACL_OBJECT_IDENTITY_ID
+BEFORE INSERT ON ACL_OBJECT_IDENTITY
+FOR EACH ROW
+BEGIN
+SELECT ACL_OBJECT_IDENTITY_SEQ.NEXTVAL INTO :new.id FROM dual;
+END;
+
+CREATE TABLE ACL_PERMISSION (
+ ID number(19,0) not null,
+ ACL_OBJECT_IDENTITY number(19,0) NOT NULL,
+ RECIPIENT varchar2(255) NOT NULL,
+ MASK number(19,0) NOT NULL,
+ primary key (ID)
+);
+
+ALTER TABLE ACL_PERMISSION ADD CONTRAINT UNIQUE_ID_RECIPIENT unique (acl_object_identity, recipient);
+
+CREATE SEQUENCE ACL_PERMISSION_SEQ;
+
+CREATE OR REPLACE TRIGGER ACL_PERMISSION_ID
+BEFORE INSERT ON ACL_PERMISSION
+FOR EACH ROW
+BEGIN
+SELECT ACL_PERMISSION_SEQ.NEXTVAL INTO :new.id FROM dual;
+END;
+
+&lt;bean id="basicAclExtendedDao" class="org.springframework.security.acl.basic.jdbc.JdbcExtendedDaoImpl"&gt;
+&lt;property name="dataSource"&gt;
+    &lt;ref bean="dataSource"/&gt;
+&lt;/property&gt;
+&lt;property name="objectPropertiesQuery" value="${acegi.objectPropertiesQuery}"/&gt;
+&lt;/bean&gt;
+
+&lt;prop key="acegi.objectPropertiesQuery"&gt;SELECT CHILD.ID, CHILD.OBJECT_IDENTITY, CHILD.ACL_CLASS, PARENT.OBJECT_IDENTITY as PARENT_OBJECT_IDENTITY FROM acl_object_identity as CHILD LEFT OUTER JOIN acl_object_identity as PARENT ON CHILD.parent_object=PARENT.id WHERE CHILD.object_identity = ?&lt;/prop&gt; </programlisting></para>
+
+    <para>The <literal>JdbcDaoImpl</literal> will only respond to requests
+    for <literal>NamedEntityObjectIdentity</literal>s. It converts such
+    identities into a single <literal>String</literal>, comprising
+    the<literal> NamedEntityObjectIdentity.getClassname()</literal> +
+    <literal>":"</literal> +
+    <literal>NamedEntityObjectIdentity.getId()</literal>. This yields the
+    type of <literal>object_identity</literal> values shown above. As
+    indicated by the sample data, each database row corresponds to a
+    single <literal>BasicAclEntry</literal>. As stated earlier and
+    demonstrated by <literal>corp.DomainObject:2</literal> in the above
+    sample data, each domain object instance will often have multiple
+    <literal>BasicAclEntry</literal>[]s.</para>
+
+    <para>As <literal>JdbcDaoImpl</literal> is required to return concrete
+    <literal>BasicAclEntry</literal> classes, it needs to know which
+    <literal>BasicAclEntry</literal> implementation it is to create and
+    populate. This is the role of the <literal>acl_class</literal> column.
+    <literal>JdbcDaoImpl</literal> will create the indicated class and set
+    its <literal>mask</literal>, <literal>recipient</literal>,
+    <literal>aclObjectIdentity</literal> and
+    <literal>aclObjectParentIdentity</literal> properties.</para>
+
+    <para>As you can probably tell from the sample data, the
+    <literal>parent_object_identity</literal> value can either be null or
+    in the same format as the <literal>object_identity</literal>. If
+    non-null, <literal>JdbcDaoImpl</literal> will create a
+    <literal>NamedEntityObjectIdentity</literal> to place inside the
+    returned <literal>BasicAclEntry</literal> class.</para>
+
+    <para>Returning to the <literal>BasicAclProvider</literal>, before it
+    can poll the <literal>BasicAclDao</literal> implementation it needs to
+    convert the domain object instance it was passed into an
+    <literal>AclObjectIdentity</literal>.
+    <literal>BasicAclProvider</literal> has a <literal>protected
+    AclObjectIdentity obtainIdentity(Object domainInstance)</literal>
+    method that is responsible for this. As a protected method, it enables
+    subclasses to easily override. The normal implementation checks
+    whether the passed domain object instance implements the
+    <literal>AclObjectIdentityAware</literal> interface, which is merely a
+    getter for an <literal>AclObjectIdentity</literal>. If the domain
+    object does implement this interface, that is the identity returned.
+    If the domain object does not implement this interface, the method
+    will attempt to create an <literal>AclObjectIdentity</literal> by
+    passing the domain object instance to the constructor of a class
+    defined by the
+    <literal>BasicAclProvider.getDefaultAclObjectIdentity()</literal>
+    method. By default the defined class is
+    <literal>NamedEntityObjectIdentity</literal>, which was described in
+    more detail above. Therefore, you will need to either (i) provide a
+    <literal>getId()</literal> method on your domain objects, (ii)
+    implement <literal>AclObjectIdentityAware</literal> on your domain
+    objects, (iii) provide an alternative
+    <literal>AclObjectIdentity</literal> implementation that will accept
+    your domain object in its constructor, or (iv) override the
+    <literal>obtainIdentity(Object)</literal> method.</para>
+
+    <para>Once the <literal>AclObjectIdentity</literal> of the domain
+    object instance is determined, the <literal>BasicAclProvider</literal>
+    will poll the DAO to obtain its <literal>BasicAclEntry</literal>[]s.
+    If any of the entries returned by the DAO indicate there is a parent,
+    that parent will be polled, and the process will repeat until there is
+    no further parent. The permissions assigned to a
+    <literal>recipient</literal> closest to the domain object instance
+    will always take priority and override any inherited permissions. From
+    the sample data above, the following inherited permissions would
+    apply:</para>
+
+    <para><programlisting>--- Mask integer 0  = no permissions
+--- Mask integer 1  = administer
+--- Mask integer 2  = read
+--- Mask integer 6  = read and write permissions
+--- Mask integer 14 = read and write and create permissions
+
+---------------------------------------------------------------------
+--- *** INHERITED RIGHTS FOR DIFFERENT INSTANCES AND RECIPIENTS ***
+--- INSTANCE  RECIPIENT         PERMISSION(S) (COMMENT #INSTANCE)
+---------------------------------------------------------------------
+---    1      ROLE_SUPERVISOR   Administer
+---    2      ROLE_SUPERVISOR   None (overrides parent #1)
+---           rod               Read
+---    3      ROLE_SUPERVISOR   Administer (from parent #1)
+---           scott             Read, Write, Create
+---    4      ROLE_SUPERVISOR   Administer (from parent #1)
+---    5      ROLE_SUPERVISOR   Administer (from parent #3)
+---           scott             Read, Write, Create (from parent #3)
+---    6      ROLE_SUPERVISOR   Administer (from parent #3)
+---           scott             Administer (overrides parent #3)</programlisting></para>
+
+    <para>So the above explains how a domain object instance has its
+    <literal>AclObjectIdentity</literal> discovered, and the
+    <literal>BasicAclDao</literal> will be polled successively until an
+    array of inherited permissions is constructed for the domain object
+    instance. The final step is to determine the
+    <literal>BasicAclEntry</literal>[]s that are actually applicable to a
+    given <literal>Authentication</literal> object.</para>
+
+    <para>As you would recall, the <literal>AclManager</literal> (and all
+    delegates, up to and including <literal>BasicAclProvider</literal>)
+    provides a method which returns only those
+    <literal>BasicAclEntry</literal>[]s applying to a passed
+    <literal>Authentication</literal> object.
+    <literal>BasicAclProvider</literal> delivers this functionality by
+    delegating the filtering operation to an
+    <literal>EffectiveAclsResolver</literal> implementation. The default
+    implementation,
+    <literal>GrantedAuthorityEffectiveAclsResolver</literal>, will iterate
+    through the <literal>BasicAclEntry</literal>[]s and include only those
+    where the <literal>recipient</literal> is equal to either the
+    <literal>Authentication</literal>'s <literal>principal</literal> or
+    any of the <literal>Authentication</literal>'s
+    <literal>GrantedAuthority</literal>[]s. Please refer to the JavaDocs
+    for more information.</para>
+
+    <mediaobject>
+      <imageobject role="html">
+        <imagedata align="center" fileref="images/Permissions.gif"
+                   format="GIF" />
+      </imageobject>
+
+      <caption>
+        <para>Figure 8: ACL Instantiation Approach</para>
+      </caption>
+    </mediaobject>
+
+    <para>The above figure explains the key relationships between objects
+    in the Basic ACL package.</para>
+  </section>
+</chapter>

src/docbkx/domain-acls.xml

@@ -0,0 +1,181 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="domain-acls">
+
+<title>Domain Object Security</title>
+
+<section id="domain-acls-overview">
+    <title>Overview</title>
+    
+    <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
+        ACL module. The new ACL module is a significant rewrite of the
+        existing ACL module. The new module can be found under the
+        <literal>org.springframework.security.acls</literal> package, with the
+        old ACL module under
+        <literal>org.springframework.security.acl</literal>. We encourage
+        users to consider testing with the new ACL module and build
+        applications with it. The old ACL module should be considered
+        deprecated and may be removed from a future release.</para>
+    
+    <para>Complex applications often will find the need to define access
+        permissions not simply at a web request or method invocation level.
+        Instead, security decisions need to comprise both who
+        (<literal>Authentication</literal>), where
+        (<literal>MethodInvocation</literal>) and what
+        (<literal>SomeDomainObject</literal>). In other words, authorization
+        decisions also need to consider the actual domain object instance
+        subject of a method invocation.</para>
+    
+    <para>Imagine you're designing an application for a pet clinic. There
+        will be two main groups of users of your Spring-based application:
+        staff of the pet clinic, as well as the pet clinic's customers. The
+        staff will have access to all of the data, whilst your customers will
+        only be able to see their own customer records. To make it a little
+        more interesting, your customers can allow other users to see their
+        customer records, such as their "puppy preschool "mentor or president
+        of their local "Pony Club". Using Spring Security as the foundation,
+        you have several approaches that can be used:<orderedlist>
+            <listitem>
+                <para>Write your business methods to enforce the security. You
+                    could consult a collection within the
+                    <literal>Customer</literal> domain object instance to determine
+                    which users have access. By using the
+                    <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
+                    you'll be able to access the <literal>Authentication</literal>
+                    object.</para>
+            </listitem>
+            
+            <listitem>
+                <para>Write an <literal>AccessDecisionVoter</literal> to enforce
+                    the security from the <literal>GrantedAuthority[]</literal>s
+                    stored in the <literal>Authentication</literal> object. This
+                    would mean your <literal>AuthenticationManager</literal> would
+                    need to populate the <literal>Authentication</literal> with
+                    custom <literal>GrantedAuthority</literal>[]s representing each
+                    of the <literal>Customer</literal> domain object instances the
+                    principal has access to.</para>
+            </listitem>
+            
+            <listitem>
+                <para>Write an <literal>AccessDecisionVoter</literal> to enforce
+                    the security and open the target <literal>Customer</literal>
+                    domain object directly. This would mean your voter needs access
+                    to a DAO that allows it to retrieve the
+                    <literal>Customer</literal> object. It would then access the
+                    <literal>Customer</literal> object's collection of approved
+                    users and make the appropriate decision.</para>
+            </listitem>
+        </orderedlist></para>
+    
+    <para>Each one of these approaches is perfectly legitimate. However,
+        the first couples your authorization checking to your business code.
+        The main problems with this include the enhanced difficulty of unit
+        testing and the fact it would be more difficult to reuse the
+        <literal>Customer</literal> authorization logic elsewhere. Obtaining
+        the <literal>GrantedAuthority[]</literal>s from the
+        <literal>Authentication</literal> object is also fine, but will not
+        scale to large numbers of <literal>Customer</literal>s. If a user
+        might be able to access 5,000 <literal>Customer</literal>s (unlikely
+        in this case, but imagine if it were a popular vet for a large Pony
+        Club!) the amount of memory consumed and time required to construct
+        the <literal>Authentication</literal> object would be undesirable. The
+        final method, opening the <literal>Customer</literal> directly from
+        external code, is probably the best of the three. It achieves
+        separation of concerns, and doesn't misuse memory or CPU cycles, but
+        it is still inefficient in that both the
+        <literal>AccessDecisionVoter</literal> and the eventual business
+        method itself will perform a call to the DAO responsible for
+        retrieving the <literal>Customer</literal> object. Two accesses per
+        method invocation is clearly undesirable. In addition, with every
+        approach listed you'll need to write your own access control list
+        (ACL) persistence and business logic from scratch.</para>
+    
+    <para>Fortunately, there is another alternative, which we'll talk
+        about below.</para>
+</section>
+
+<section id="domain-acls-key-concepts">
+    <title>Key Concepts</title>
+    
+    <para>The org.springframework.security.acls package should be
+        consulted for its major interfaces. The key interfaces are:</para>
+    
+    <itemizedlist spacing="compact">
+        <listitem>
+            <para><literal>Acl</literal>: Every domain object has one and only
+                one <literal>Acl</literal> object, which internally holds the
+                <literal>AccessControlEntry</literal>s as well as knows the owner
+                of the <literal>Acl</literal>. An Acl does not refer directly to
+                the domain object, but instead to an
+                <literal>ObjectIdentity</literal>.</para>
+        </listitem>
+        
+        <listitem>
+            <para><literal><literal>AccessControlEntry</literal></literal>: An
+                Acl holds multiple <literal>AccessControlEntry</literal>s, which
+                are often abbreviated as ACEs in the framework. Each ACE refers to
+                a specific tuple of <literal>Permission</literal>,
+                <literal>Sid</literal> and <literal>Acl</literal>. An ACE can also
+                be granting or non-granting and contain audit settings.</para>
+        </listitem>
+        
+        <listitem>
+            <para><literal>Permission</literal>: A permission represents an
+                immutable particular bit mask, and offers convenience functions
+                for bit masking and outputting information.</para>
+        </listitem>
+        
+        <listitem>
+            <para><literal>Sid</literal>: The ACL module needs to refer to
+                principals and <literal>GrantedAuthority[]</literal>s. A level of
+                indirection is provided by the <literal>Sid</literal> interface.
+                Common classes include <literal>PrincipalSid</literal> (to
+                represent the principal inside an
+                <literal>Authentication</literal> object) and
+                <literal>GrantedAuthoritySid</literal>.</para>
+        </listitem>
+        
+        <listitem>
+            <para><literal>ObjectIdentity</literal>: Each domain object is
+                represented internally within the ACL module by an
+                <literal>ObjectIdentity</literal>.</para>
+        </listitem>
+        
+        <listitem>
+            <para><literal>AclService</literal>: Retrieves the
+                <literal>Acl</literal> applicable for a given
+                <literal>ObjectIdentity</literal>.</para>
+        </listitem>
+        
+        <listitem>
+            <para><literal>MutableAclService</literal>: Allows a modified
+                <literal>Acl</literal> to be presented for persistence. It is not
+                essential to use this interface if you do not wish.</para>
+        </listitem>
+    </itemizedlist>
+    
+    <para>The ACL module was based on extensive feedback from the user
+        community following real-world use of the original ACL module. This
+        feedback resulted in a rearchitecture of the ACL module to offer
+        significantly enhanced performance (particularly in the area of
+        database retrieval), significantly better encapsulation, higher
+        cohesion, and enhanced customisation points.</para>
+    
+    <para>The Contacts Sample that ships with Acegi Security 1.0.3 offers
+        a demonstration of the new ACL module. Converting Contacts from using
+        the old module to the new module was relatively simple, and users of
+        the old ACL module will likely find their applications can be modified
+        with relatively little work.</para>
+    
+    <para>We will document the new ACL module more fully with a subsequent
+        release. Please note that the new ACL module should be considered a
+        preview only (ie do not use in production without proper prior
+        testing), and there is a small chance there may be changes between
+        1.0.3 and 1.1.0 when it will become final. Nevertheless,
+        compatibility-affecting changes are considered quite unlikely,
+        especially given the module is already based on several years of
+        feedback from users of the original ACL module.</para>
+</section>
+</chapter>

src/docbkx/form-authentication.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="form">
+    <title>Form Authentication Mechanism</title>
+    
+    <sect1 id="form-overview">
+        <title>Overview</title>
+        
+        <para>HTTP Form Authentication involves using the
+            <literal>AuthenticationProcessingFilter</literal> to process a login
+            form. This is the most common way that application authenticate end
+            users. Form-based authentication is entirely compatible with the DAO
+            and JAAS authentication providers.</para>
+    </sect1>
+    
+    <sect1 id="form-config">
+        <title>Configuration</title>
+        
+        <para>The login form simply contains <literal>j_username</literal> and
+            <literal>j_password</literal> input fields, and posts to a URL that is
+            monitored by the filter (by default
+            <literal>j_spring_security_check</literal>). The filter is defined in
+            <literal>web.xml</literal> behind a
+            <literal>FilterToBeanProxy</literal> as follows:</para>
+        
+        <para><programlisting>&lt;filter&gt;
+            &lt;filter-name&gt;Acegi Authentication Processing Filter&lt;/filter-name&gt;
+            &lt;filter-class&gt;org.springframework.security.util.FilterToBeanProxy&lt;/filter-class&gt;
+            &lt;init-param&gt;
+            &lt;param-name&gt;targetClass&lt;/param-name&gt;
+            &lt;param-value&gt;org.springframework.security.ui.webapp.AuthenticationProcessingFilter&lt;/param-value&gt;
+            &lt;/init-param&gt;
+            &lt;/filter&gt;
+            
+            &lt;filter-mapping&gt;
+            &lt;filter-name&gt;Acegi Authentication Processing Filter&lt;/filter-name&gt;
+            &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+            &lt;/filter-mapping&gt;</programlisting></para>
+        
+        <para>For a discussion of <literal>FilterToBeanProxy</literal>, please
+            refer to the Filters section. The application context will need to
+            define the <literal>AuthenticationProcessingFilter</literal>:</para>
+        
+        <para><programlisting>&lt;bean id="authenticationProcessingFilter"
+            class="org.springframework.security.ui.webapp.AuthenticationProcessingFilter"&gt;
+            &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+            &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/acegilogin.jsp?login_error=1&lt;/value&gt;&lt;/property&gt;
+            &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/&lt;/value&gt;&lt;/property&gt;
+            &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_spring_security_check&lt;/value&gt;&lt;/property&gt;
+            &lt;/bean&gt;        </programlisting></para>
+        
+        <para>The configured <literal>AuthenticationManager</literal>
+            processes each authentication request. If authentication fails, the
+            browser will be redirected to the
+            <literal>authenticationFailureUrl</literal>. The
+            <literal>AuthenticationException</literal> will be placed into the
+            <literal>HttpSession</literal> attribute indicated by
+            <literal>AbstractProcessingFilter.ACEGI_SECURITY_LAST_EXCEPTION_KEY</literal>,
+            enabling a reason to be provided to the user on the error page.</para>
+        
+        <para>If authentication is successful, the resulting
+            <literal>Authentication</literal> object will be placed into the
+            <literal>SecurityContextHolder</literal>.</para>
+        
+        <para>Once the <literal>SecurityContextHolder</literal> has been
+            updated, the browser will need to be redirected to the target URL. The
+            target URL is usually indicated by the <literal>HttpSession</literal>
+            attribute specified by
+            <literal>AbstractProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY</literal>.
+            This attribute is automatically set by the
+            <literal>ExceptionTranslationFilter</literal> when an
+            <literal>AuthenticationException</literal> occurs, so that after login
+            is completed the user can return to what they were trying to access.
+            If for some reason the <literal>HttpSession</literal> does not
+            indicate the target URL, the browser will be redirected to the
+            <literal>defaultTargetUrl</literal> property.</para>
+    </sect1>
+</chapter>

src/docbkx/introduction.xml

@@ -0,0 +1,282 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="introduction">
+    
+<title>Introduction</title>
+
+<sect1 id="what-is-acegi-security">
+    <title>What is Spring Security?</title>
+    
+    <para>Spring Security provides comprehensive security services for
+        J2EE-based enterprise software applications. There is a particular
+        emphasis on supporting projects built using The Spring Framework,
+        which is the leading J2EE solution for enterprise software
+        development. If you're not using Spring for developing enterprise
+        applications, we warmly encourage you to take a closer look at it.
+        Some familiarity with Spring - and in particular dependency injection
+        principles - will help you get up to speed with Spring Security more
+        easily.</para>
+    
+    <para>People use Spring Security for many reasons, but most are drawn
+        to the project after finding the security features of J2EE's Servlet
+        Specification or EJB Specification lack the depth required for typical
+        enterprise application scenarios. Whilst mentioning these standards,
+        it's important to recognise that they are not portable at a WAR or EAR
+        level. Therefore, if you switch server environments, it is typically a
+        lot of work to reconfigure your application's security in the new
+        target environment. Using Spring Security overcomes these problems,
+        and also brings you dozens of other useful, entirely customisable
+        security features.</para>
+    
+    <para>As you probably know, security comprises two major operations.
+        The first is known as "authentication", which is the process of
+        establishing a principal is who they claim to be. A "principal"
+        generally means a user, device or some other system which can perform
+        an action in your application. "Authorization" refers to the process
+        of deciding whether a principal is allowed to perform an action in
+        your application. To arrive at the point where an authorization
+        decision is needed, the identity of the principal has already been
+        established by the authentication process. These concepts are common,
+        and not at all specific to Spring Security.</para>
+    
+    <para>At an authentication level, Spring Security supports a wide
+        range of authentication models. Most of these authentication models
+        are either provided by third parties, or are developed by relevant
+        standards bodies such as the Internet Engineering Task Force. In
+        addition, Spring Security provides its own set of authentication
+        features. Specifically, Spring Security currently supports
+        authentication integration with all of these technologies:</para>
+    
+    <itemizedlist spacing="compact">
+        <listitem>
+            <para>HTTP BASIC authentication headers (an IEFT RFC-based
+                standard)</para>
+        </listitem>
+        
+        <listitem>
+            <para>HTTP Digest authentication headers (an IEFT RFC-based
+                standard)</para>
+        </listitem>
+        
+        <listitem>
+            <para>HTTP X.509 client certificate exchange (an IEFT RFC-based
+                standard)</para>
+        </listitem>
+        
+        <listitem>
+            <para>LDAP (a very common approach to cross-platform
+                authentication needs, especially in large environments)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Form-based authentication (for simple user interface
+                needs)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Computer Associates Siteminder</para>
+        </listitem>
+        
+        <listitem>
+            <para>JA-SIG Central Authentication Service (otherwise known as
+                CAS, which is a popular open source single sign on system)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Transparent authentication context propagation for Remote
+                Method Invocation (RMI) and HttpInvoker (a Spring remoting
+                protocol)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Automatic "remember-me" authentication (so you can tick a
+                box to avoid re-authentication for a predetermined period of
+                time)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Anonymous authentication (allowing every call to
+                automatically assume a particular security identity)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Run-as authentication (which is useful if one call should
+                proceed with a different security identity)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Java Authentication and Authorization Service (JAAS)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Container integration with JBoss, Jetty, Resin and Tomcat
+                (so you can still use Container Manager Authentication if
+                desired)</para>
+        </listitem>
+        
+        <listitem>
+            <para>Java Open Source Single Sign On (JOSSO) *</para>
+        </listitem>
+        
+        <listitem>
+            <para>OpenNMS Network Management Platform *</para>
+        </listitem>
+        
+        <listitem>
+            <para>AppFuse *</para>
+        </listitem>
+        
+        <listitem>
+            <para>AndroMDA *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Mule ESB *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Direct Web Request (DWR) *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Grails *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Tapestry *</para>
+        </listitem>
+        
+        <listitem>
+            <para>JTrac *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Jasypt *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Roller *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Elastic Plath *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Atlassian Crowd *</para>
+        </listitem>
+        
+        <listitem>
+            <para>Your own authentication systems (see below)</para>
+        </listitem>
+    </itemizedlist>
+    
+    <para>(* Denotes provided by a third party; check our <ulink
+        url="http://acegisecurity.org/powering.html">integration page</ulink>
+        for links to the latest details)</para>
+    
+    <para>Many independent software vendors (ISVs) adopt Spring Security
+        because of this significant choice of flexible authentication models.
+        Doing so allows them to quickly integrate their solutions with
+        whatever their end clients need, without undertaking a lot of
+        engineering or requiring the client to change their environment. If
+        none of the above authentication mechanisms suit your needs, Spring
+        Security is an open platform and it is quite simple to write your own
+        authentication mechanism. Many corporate users of Spring Security need
+        to integrate with "legacy" systems that don't follow any particular
+        security standards, and Spring Security is happy to "play nicely" with
+        such systems.</para>
+    
+    <para>Sometimes the mere process of authentication isn't enough.
+        Sometimes you need to also differentiate security based on the way a
+        principal is interacting with your application. For example, you might
+        want to ensure requests only arrive over HTTPS, in order to protect
+        passwords from eavesdropping or end users from man-in-the-middle
+        attacks. Or, you might want to ensure that an actual human being is
+        making the requests and not some robot or other automated process.
+        This is especially helpful to protect password recovery processes from
+        brute force attacks, or simply to make it harder for people to
+        duplicate your application's key content. To help you achieve these
+        goals, Spring Security fully supports automatic "channel security",
+        together with JCaptcha integration for human user detection.</para>
+    
+    <para>Irrespective of how authentication was undertaken, Spring
+        Security provides a deep set of authorization capabilities. There are
+        three main areas of interest in respect of authorization, these being
+        authorizing web requests, authorizing methods can be invoked, and
+        authorizing access to individual domain object instances. To help you
+        understand the differences, consider the authorization capabilities
+        found in the Servlet Specification web pattern security, EJB Container
+        Managed Security and file system security respectively. Spring
+        Security provides deep capabilities in all of these important areas,
+        which we'll explore later in this reference guide.</para>
+</sect1>
+
+<sect1 id="history">
+    <title>History</title>
+    
+    <para>Spring Security began in late 2003 as "The Acegi Security System
+        for Spring". A question was posed on the Spring Developers' mailing
+        list asking whether there had been any consideration given to a
+        Spring-based security implementation. At the time the Spring community
+        was relatively small (especially by today's size!), and indeed Spring
+        itself had only existed as a SourceForge project from early 2003. The
+        response to the question was that it was a worthwhile area, although a
+        lack of time currently prevented its exploration.</para>
+    
+    <para>With that in mind, a simple security implementation was built
+        and not released. A few weeks later another member of the Spring
+        community inquired about security, and at the time this code was
+        offered to them. Several other requests followed, and by January 2004
+        around twenty people were using the code. These pioneering users were
+        joined by others who suggested a SourceForge project was in order,
+        which was duly established in March 2004.</para>
+    
+    <para>In those early days, the project didn't have any of its own
+        authentication modules. Container Managed Security was relied upon for
+        the authentication process, with Acegi Security instead focusing on
+        authorization. This was suitable at first, but as more and more users
+        requested additional container support, the fundamental limitation of
+        container-specific authentication realm interfaces was experienced.
+        There was also a related issue of adding new JARs to the container's
+        classpath, which was a common source of end user confusion and
+        misconfiguration.</para>
+    
+    <para>Acegi Security-specific authentication services were
+        subsequently introduced. Around a year later, Acegi Security became an
+        official Spring Framework subproject. The 1.0.0 final release was
+        published in May 2006 - after more than two and a half years of active
+        use in numerous production software projects and many hundreds of
+        improvements and community contributions.</para>
+    
+    <para>Since work began on the 2.0 release, the project has been
+        rebranded as "Spring Security".</para>
+    
+    <para>Today Spring Security enjoys a strong and active open source
+        community. There are thousands of messages about Spring Security on
+        the support forums. Fourteen developers work on the code itself, with
+        an active community who also regularly share patches and support their
+        peers.</para>
+</sect1>
+
+<sect1 id="release-numbering">
+    <title>Release Numbering</title>
+    
+    <para>It is useful to understand how Spring Security release numbers
+        work, as it will help you identify the effort (or lack thereof)
+        involved in migrating to future releases of the project. Officially,
+        we use the Apache Portable Runtime Project versioning guidelines,
+        which can be viewed at
+        <literal>http://apr.apache.org/versioning.html</literal>. We quote the
+        introduction contained on that page for your convenience:</para>
+    
+    <para><quote>Versions are denoted using a standard triplet of
+        integers: MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions
+        are incompatible, large-scale upgrades of the API. MINOR versions
+        retain source and binary compatibility with older minor versions, and
+        changes in the PATCH level are perfectly compatible, forwards and
+        backwards.</quote></para>
+</sect1>
+</chapter>

src/docbkx/jaas-auth-provider.xml

@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter id="jaas">
+    <title>Java Authentication and Authorization Service (JAAS)
+        Provider</title>
+    
+    <sect1 id="jaas-overview">
+        <title>Overview</title>
+        
+        <para>Spring Security provides a package able to delegate
+            authentication requests to the Java Authentication and Authorization
+            Service (JAAS). This package is discussed in detail below.</para>
+        
+        <para>Central to JAAS operation are login configuration files. To
+            learn more about JAAS login configuration files, consult the JAAS
+            reference documentation available from Sun Microsystems. We expect you
+            to have a basic understanding of JAAS and its login configuration file
+            syntax in order to understand this section.</para>
+    </sect1>
+    
+    <sect1 id="jaas-config">
+        <title>Configuration</title>
+        
+        <para>The <literal>JaasAuthenticationProvider</literal> attempts to
+            authenticate a user’s principal and credentials through JAAS.</para>
+        
+        <para>Let’s assume we have a JAAS login configuration file,
+            <literal>/WEB-INF/login.conf</literal>, with the following
+            contents:</para>
+        
+        <para><programlisting>JAASTest {
+            sample.SampleLoginModule required;
+            };</programlisting></para>
+        
+        <para>Like all Spring Security beans, the
+            <literal>JaasAuthenticationProvider</literal> is configured via the
+            application context. The following definitions would correspond to the
+            above JAAS login configuration file:</para>
+        
+        <para><programlisting>
+            <![CDATA[ &lt;bean id="jaasAuthenticationProvider"
+            class="org.springframework.security.providers.jaas.JaasAuthenticationProvider"&gt;
+  &lt;property name="loginConfig"&gt;
+    &lt;value&gt;/WEB-INF/login.conf&lt;/value&gt;
+  &lt;/property&gt;
+  &lt;property name="loginContextName"&gt;
+    &lt;value&gt;JAASTest&lt;/value&gt;
+  &lt;/property&gt;
+  &lt;property name="callbackHandlers"&gt;
+    &lt;list&gt;
+      &lt;bean class="org.springframework.security.providers.jaas.JaasNameCallbackHandler"/&gt;
+      &lt;bean class="org.springframework.security.providers.jaas.JaasPasswordCallbackHandler"/&gt;
+    &lt;/list&gt;
+  &lt;/property&gt;
+  &lt;property name="authorityGranters"&gt;
+    &lt;list&gt;
+      &lt;bean class="org.springframework.security.providers.jaas.TestAuthorityGranter"/&gt;
+    &lt;/list&gt;
+  &lt;/property&gt;
+&lt;/bean&gt; ]]>
+
+        </programlisting></para>
+        
+        <para>The <literal>CallbackHandler</literal>s and
+            <literal>AuthorityGranter</literal>s are discussed below.</para>
+        
+        <sect2 id="jaas-callbackhandler">
+            <title id="jaas-callback-handler">JAAS CallbackHandler</title>
+            
+            <para>Most JAAS <literal>LoginModule</literal>s require a callback
+                of some sort. These callbacks are usually used to obtain the
+                username and password from the user.</para>
+            
+            <para>In a Spring Security deployment, Spring Security is
+                responsible for this user interaction (via the authentication
+                mechanism). Thus, by the time the authentication request is
+                delegated through to JAAS, Spring Security's authentication
+                mechanism will already have fully-populated an
+                <literal>Authentication</literal> object containing all the
+                information required by the JAAS
+                <literal>LoginModule</literal>.</para>
+            
+            <para>Therefore, the JAAS package for Spring Security provides two
+                default callback handlers,
+                <literal>JaasNameCallbackHandler</literal> and
+                <literal>JaasPasswordCallbackHandler</literal>. Each of these
+                callback handlers implement
+                <literal>JaasAuthenticationCallbackHandler</literal>. In most cases
+                these callback handlers can simply be used without understanding the
+                internal mechanics.</para>
+            
+            <para>For those needing full control over the callback behavior,
+                internally <literal>JaasAutheticationProvider</literal> wraps these
+                <literal>JaasAuthenticationCallbackHandler</literal>s with an
+                <literal>InternalCallbackHandler</literal>. The
+                <literal>InternalCallbackHandler</literal> is the class that
+                actually implements JAAS’ normal <literal>CallbackHandler</literal>
+                interface. Any time that the JAAS <literal>LoginModule</literal> is
+                used, it is passed a list of application context configured
+                <literal>InternalCallbackHandler</literal>s. If the
+                <literal>LoginModule</literal> requests a callback against the
+                <literal>InternalCallbackHandler</literal>s, the callback is in-turn
+                passed to the <literal>JaasAuthenticationCallbackHandler</literal>s
+                being wrapped.</para>
+        </sect2>
+        
+        <sect2 id="jaas-authoritygranter">
+            <title id="jaas-authority-granter">JAAS AuthorityGranter</title>
+            
+            <para>JAAS works with principals. Even "roles" are represented as
+                principals in JAAS. Spring Security, on the other hand, works with
+                <literal>Authentication</literal> objects. Each
+                <literal>Authentication</literal> object contains a single
+                principal, and multiple <literal>GrantedAuthority</literal>[]s. To
+                facilitate mapping between these different concepts, Spring
+                Security's JAAS package includes an
+                <literal>AuthorityGranter</literal> interface.</para>
+            
+            <para>An <literal>AuthorityGranter</literal> is responsible for
+                inspecting a JAAS principal and returning a
+                <literal>String</literal>. The
+                <literal>JaasAuthenticationProvider</literal> then creates a
+                <literal>JaasGrantedAuthority</literal> (which implements Spring
+                Security’s <literal>GrantedAuthority</literal> interface) containing
+                both the <literal>AuthorityGranter</literal>-returned
+                <literal>String</literal> and the JAAS principal that the
+                <literal>AuthorityGranter</literal> was passed. The
+                <literal>JaasAuthenticationProvider</literal> obtains the JAAS
+                principals by firstly successfully authenticating the user’s
+                credentials using the JAAS <literal>LoginModule</literal>, and then
+                accessing the <literal>LoginContext</literal> it returns. A call to
+                <literal>LoginContext.getSubject().getPrincipals()</literal> is
+                made, with each resulting principal passed to each
+                <literal>AuthorityGranter</literal> defined against the
+                <literal>JaasAuthenticationProvider.setAuthorityGranters(List)</literal>
+                property.</para>
+            
+            <para>Spring Security does not include any production
+                <literal>AuthorityGranter</literal>s given that every JAAS principal
+                has an implementation-specific meaning. However, there is a
+                <literal>TestAuthorityGranter</literal> in the unit tests that
+                demonstrates a simple <literal>AuthorityGranter</literal>
+                implementation.</para>
+        </sect2>
+    </sect1>
+</chapter>

src/docbkx/ldap-auth-provider.xml

@@ -0,0 +1,194 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+<chapter id="ldap">
+    <title>LDAP Authentication</title>
+    <sect1 id="ldap-overview">
+        <title>Overview</title>
+        <para>LDAP is often used by organizations as a central repository for user information and
+            as an authentication service. It can also be used to store the role information for
+            application users.</para>
+        <para>There are many different scenarios for how an LDAP server may be configured so Spring
+            Security's LDAP provider is fully configurable. It uses separate strategy interfaces for
+            authentication and role retrieval and provides default implementations which can be
+            configured to handle a wide range of situations.</para>
+        <para>You should be familiar with LDAP before trying to use it with Spring Security. The
+            following link provides a good introduction to the concepts involved and a guide to
+            setting up a directory using the free LDAP server OpenLDAP: <ulink
+                url="http://www.zytrax.com/books/ldap/"/>. Some familiarity with the JNDI APIs used
+            to access LDAP from Java may also be useful. We don't use any third-party LDAP libraries
+            (Mozilla/Netscape, JLDAP etc.) in the LDAP provider.</para>
+    </sect1>
+    <sect1 id="ldap-with-acegi">
+        <title>Using LDAP with Spring Security</title>
+        <para>The main LDAP provider class is
+                <classname>org.springframework.security.providers.ldap.LdapAuthenticationProvider</classname>.
+            This bean doesn't actually do much itself other than implement the
+                <methodname>retrieveUser</methodname> method required by its base class,
+                <classname>AbstractUserDetailsAuthenticationProvider</classname>. It delegates the
+            work to two other beans, an <interfacename>LdapAuthenticator</interfacename> and an
+                <interfacename>LdapAuthoritiesPopulator</interfacename> which are responsible for
+            authenticating the user and retrieving the user's set of
+            <interfacename>GrantedAuthority</interfacename>s respectively.</para>
+        <sect2 id="ldap-ldap-authenticators">
+            <title>LdapAuthenticator Implementations</title>
+            <para>The authenticator is also responsible for retrieving any required user attributes.
+                This is because the permissions on the attributes may depend on the type of
+                authentication being used. For example, if binding as the user, it may be necessary
+                to read them with the user's own permissions.</para>
+            <para>There are currently two authentication strategies supplied with Spring Security: <itemizedlist>
+                    <listitem>
+                        <para>Authentication directly to the LDAP server ("bind"
+                        authentication).</para>
+                    </listitem>
+                    <listitem>
+                        <para>Password comparison, where the password supplied by the user is
+                            compared with the one stored in the repository. This can either be done
+                            by retrieving the value of the password attribute and checking it
+                            locally or by performing an LDAP "compare" operation, where the supplied
+                            password is passed to the server for comparison and the real password
+                            value is never retrieved.</para>
+                    </listitem>
+                </itemizedlist></para>
+            <sect3 id="ldap-ldap-authenticators-common">
+                <title>Common Functionality</title>
+                <para>Before it is possible to authenticate a user (by either strategy), the
+                    distinguished name (DN) has to be obtained from the login name supplied to the
+                    application. This can be done either by simple pattern-matching (by setting the
+                        <property>setUserDnPatterns</property> array property) or by setting the
+                        <property>userSearch</property> property. For the DN pattern-matching
+                    approach, a standard Java pattern format is used, and the login name will be
+                    substituted for the parameter <parameter>{0}</parameter>. The pattern should be
+                    relative to the DN that the configured
+                    <interfacename>InitialDirContextFactory</interfacename> will bind to (see the
+                    section on <link linkend="ldap-dircontextfactory">connecting to the LDAP
+                    server</link> for more information on this). For example, if you are using an
+                    LDAP server specified by the URL <literal
+                        >ldap://monkeymachine.co.uk/dc=springframework,dc=org</literal>, and have a
+                    pattern <literal>uid={0},ou=greatapes</literal>, then a login name of "gorilla"
+                    will map to a DN <literal
+                    >uid=gorilla,ou=greatapes,dc=springframework,dc=org</literal>. Each configured
+                    DN pattern will be tried in turn until a match is found. For information on
+                    using a search, see the section on <link linkend="ldap-searchobjects">search
+                        objects</link> below. A combination of the two approaches can also be used -
+                    the patterns will be checked first and if no matching DN is found, the search
+                    will be used.</para>
+            </sect3>
+            <sect3 id="ldap-ldap-authenticators-bind">
+                <title>BindAuthenticator</title>
+                <para>The class
+                        <classname>org.springframework.security.providers.ldap.authenticator.BindAuthenticator</classname>
+                    implements the bind authentication strategy. It simply attempts to bind as the
+                    user.</para>
+            </sect3>
+            <sect3 id="ldap-ldap-authenticators-password">
+                <title>PasswordComparisonAuthenticator</title>
+                <para>The class
+                        <classname>org.springframework.security.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
+                    implements the password comparison authentication strategy.</para>
+            </sect3>
+            <sect3 id="ldap-ldap-authenticators-active-directory">
+                <title>Active Directory Authentication</title>
+                <para>In addition to standard LDAP authentication (binding with a DN), Active
+                    Directory has its own non-standard syntax for user authentication.</para>
+            </sect3>
+        </sect2>
+        <sect2 id="ldap-dircontextfactory">
+            <title>Connecting to the LDAP Server</title>
+            <para>The beans discussed above have to be able to connect to the server. They both have
+                to be supplied with an <interfacename>InitialDirContextFactory</interfacename>
+                instance. Unless you have special requirements, this will usually be a
+                    <classname>DefaultInitialDirContextFactory</classname> bean, which can be
+                configured with the URL of your LDAP server and optionally with the username and
+                password of a "manager" user which will be used by default when binding to the
+                server (instead of binding anonymously). It currently supports "simple" LDAP
+                authentication.</para>
+            <para><classname>DefaultInitialDirContextFactory</classname> uses Sun's JNDI LDAP
+                implementation by default (the one that comes with the JDK). It also supports the
+                built in connection pooling offered by Sun's provider. Connections which are
+                obtained either anonymously or with the "manager" user's identity will be pooled
+                automatically. Connections obtained with a specific user's identity will not be
+                pooled. Connection pooling can be disabled completely by setting the <property
+                    >useConnectionPool</property> property to false.</para>
+            <para>See the <ulink
+                    url="http://acegisecurity.org/multiproject/acegi-security/xref/org/acegisecurity/providers/ldap/DefaultInitialDirContextFactory.html"
+                    >class Javadoc and source</ulink> for more information on this bean and its
+                properties.</para>
+        </sect2>
+        <sect2 id="ldap-searchobjects">
+            <title>LDAP Search Objects</title>
+            <para>Often more a more complicated strategy than simple DN-matching is required to
+                locate a user entry in the directory. This can be encapsulated in an
+                    <interfacename>LdapUserSearch</interfacename> instance which can be supplied to
+                the authenticator implementations, for example, to allow them to locate a user. The
+                supplied implementation is <classname>FilterBasedLdapUserSearch</classname>.</para>
+            <sect3 id="ldap-searchobjects-filter">
+                <title id="ldap-searchobjects-filter-based"
+                    ><classname>FilterBasedLdapUserSearch</classname></title>
+                <para>This bean uses an LDAP filter to match the user object in the directory. The
+                    process is explained in the Javadoc for the corresponding search method on the
+                        <ulink
+                        url="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)"
+                        >JDK DirContext class</ulink>. As explained there, the search filter can be
+                    supplied with parameters. For this class, the only valid parameter is <parameter
+                        >{0}</parameter> which will be replaced with the user's login name.</para>
+            </sect3>
+        </sect2>
+    </sect1>
+    <sect1 id="ldap-config">
+        <title>Configuration</title>
+        <para>There is a version of the <link linkend="contacts-sample">Contacts Sample
+            Application</link> which uses LDAP. You can copy the beans and filter setup from this as
+            a starting point for configuring your own application.</para>
+        <para>A typical configuration, using some of the beans we've discussed above, might look
+            like this: <programlisting>            
+            <![CDATA[                 
+<bean id="initialDirContextFactory"
+        class="org.springframework.security.ldap.DefaultInitialDirContextFactory">
+    <constructor-arg value="ldap://monkeymachine:389/dc=springframework,dc=org"/>
+    <property name="managerDn"><value>cn=manager,dc=springframework,dc=org</value></property>
+    <property name="managerPassword"><value>password</value></property>
+</bean>
+
+<bean id="userSearch"
+        class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
+    <constructor-arg index="0" value=""/>
+    <constructor-arg index="1" value="(uid={0})"/>
+    <constructor-arg index="2">
+        <ref local="initialDirContextFactory" />
+    </constructor-arg>
+    <property name="searchSubtree" value="true"/>
+</bean>
+
+<bean id="ldapAuthProvider"
+        class="org.springframework.security.providers.ldap.LdapAuthenticationProvider">
+    <constructor-arg>
+        <bean class="org.springframework.security.providers.ldap.authenticator.BindAuthenticator">
+            <constructor-arg><ref local="initialDirContextFactory"/></constructor-arg>
+            <property name="userDnPatterns"><list><value>uid={0},ou=people</value></list></property>
+        </bean>
+    </constructor-arg>
+    <constructor-arg>
+        <bean class="org.springframework.security.ldap.populator.DefaultLdapAuthoritiesPopulator">
+            <constructor-arg><ref local="initialDirContextFactory"/></constructor-arg>
+            <constructor-arg><value>ou=groups</value></constructor-arg>
+            <property name="groupRoleAttribute"><value>ou</value></property>
+        </bean>
+    </constructor-arg>
+</bean> 
+]]>              
+</programlisting> This would set up the provider to access an LDAP server with URL
+                <literal>ldap://monkeymachine:389/dc=springframework,dc=org</literal>.
+            Authentication will be performed by attempting to bind with the DN <literal
+                >uid=&lt;user-login-name&gt;,ou=people,dc=springframework,dc=org</literal>. After
+            successful authentication, roles will be assigned to the user by searching under the DN
+                <literal>ou=groups,dc=springframework,dc=org</literal> with the default filter
+                <literal>(member=&lt;user's-DN&gt;)</literal>. The role name will be taken from the
+                <quote>ou</quote> attribute of each match.</para>
+        <para>We've also included the configuration for a user search object, which uses the filter
+                <literal>(uid=&lt;user-login-name&gt;)</literal>. This could be used instead of the
+            DN-pattern (or in addition to it), by setting the authenticator's <property
+            >userSearch</property> property. The authenticator would then call the search object to
+            obtain the correct user's DN before attempting to bind as this user.</para>
+    </sect1>
+</chapter>

src/docbkx/remember-me-authentication.xml

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">  
+
+<chapter id="remember-me">
+<title>Remember-Me Authentication</title>
+
+<sect1 id="remember-me-overview">
+    <title>Overview</title>
+    
+    <para>Remember-me authentication refers to web sites being able to
+        remember the identity of a principal between sessions. This is
+        typically accomplished by sending a cookie to the browser, with the
+        cookie being detected during future sessions and causing automated
+        login to take place. Spring Security provides the necessary hooks so
+        that such operations can take place, along with providing a concrete
+        implementation that uses hashing to preserve the security of
+        cookie-based tokens.</para>
+</sect1>
+
+<sect1 id="remember-me-config">
+    <title>Configuration</title>
+    
+    <para>Remember-me authentication is not used with basic
+        authentication, given it is often not used with
+        <literal>HttpSession</literal>s. Remember-me is used with
+        <literal>AuthenticationProcessingFilter</literal>, and is implemented
+        via hooks in the <literal>AbstractProcessingFilter</literal>
+        superclass. The hooks will invoke a concrete
+        <literal>RememberMeServices</literal> at the appropriate times. The
+        interface looks like this:</para>
+    
+    <para><programlisting>public Authentication autoLogin(HttpServletRequest request, HttpServletResponse response);
+        public void loginFail(HttpServletRequest request, HttpServletResponse response);
+        public void loginSuccess(HttpServletRequest request, HttpServletResponse response, Authentication successfulAuthentication);</programlisting></para>
+    
+    <para>Please refer to JavaDocs for a fuller discussion on what the
+        methods do, although note at this stage
+        <literal>AbstractProcessingFilter</literal> only calls the
+        <literal>loginFail()</literal> and <literal>loginSuccess()</literal>
+        methods. The <literal>autoLogin()</literal> method is called by
+        <literal>RememberMeProcessingFilter</literal> whenever the
+        <literal>SecurityContextHolder</literal> does not contain an
+        <literal>Authentication</literal>. This interface therefore provides
+        the underlaying remember-me implementation with sufficient
+        notification of authentication-related events, and delegates to the
+        implementation whenever a candidate web request might contain a cookie
+        and wish to be remembered.</para>
+    
+    <para>This design allows any number of remember-me implementation
+        strategies. In the interests of simplicity and avoiding the need for
+        DAO implementations that specify write and create methods, Acegi
+        Security's only concrete implementation,
+        <literal>TokenBasedRememberMeServices</literal>, uses hashing to
+        achieve a useful remember-me strategy. In essence a cookie is sent to
+        the browser upon successful interactive authentication, with that
+        cookie being composed as follows:</para>
+    
+    <para><programlisting>base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key))
+        
+        username:         As identifiable to TokenBasedRememberMeServices.getUserDetailsService()
+        password:         That matches the relevant UserDetails retrieved from TokenBasedRememberMeServices.getUserDetailsService()
+        expirationTime:   The date and time when the remember-me token expires, expressed in milliseconds
+        key:              A private key to prevent modification of the remember-me token
+    </programlisting></para>
+    
+    <para>As such the remember-me token is valid only for the period
+        specified, and provided that the username, password and key does not
+        change. Notably, this has a potential security issue in that a
+        captured remember-me token will be usable from any user agent until
+        such time as the token expires. This is the same issue as with digest
+        authentication. If a principal is aware a token has been captured,
+        they can easily change their password and immediately invalidate all
+        remember-me tokens on issue. However, if more significant security is
+        needed a rolling token approach should be used (this would require a
+        database) or remember-me services should simply not be used.</para>
+    
+    <para><literal>TokenBasedRememberMeServices</literal> generates a
+        <literal>RememberMeAuthenticationToken</literal>, which is processed
+        by <literal>RememberMeAuthenticationProvider</literal>. A
+        <literal>key</literal> is shared between this authentication provider
+        and the <literal>TokenBasedRememberMeServices</literal>. In addition,
+        <literal>TokenBasedRememberMeServices</literal> requires A
+        UserDetailsService from which it can retrieve the username and
+        password for signature comparison purposes, and generate the
+        <literal>RememberMeAuthenticationToken</literal> to contain the
+        correct <literal>GrantedAuthority</literal>[]s. Some sort of logout
+        command should be provided by the application (typically via a JSP)
+        that invalidates the cookie upon user request. See the Contacts Sample
+        application's <literal>logout.jsp</literal> for an example.</para>
+    
+    <para>The beans required in an application context to enable
+        remember-me services are as follows:</para>
+    
+    <para><programlisting>
+        &lt;bean id="rememberMeProcessingFilter"
+        class="org.springframework.security.ui.rememberme.RememberMeProcessingFilter"&gt;
+        &lt;property name="rememberMeServices"&gt;&lt;ref local="rememberMeServices"/&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="rememberMeServices" class="org.springframework.security.ui.rememberme.TokenBasedRememberMeServices"&gt;
+        &lt;property name="userDetailsService"&gt;&lt;ref local="jdbcDaoImpl"/&gt;&lt;/property&gt;
+        &lt;property name="key"&gt;&lt;value&gt;springRocks&lt;/value&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+        &lt;bean id="rememberMeAuthenticationProvider"
+        class="org.springframework.security.providers.rememberme.RememberMeAuthenticationProvider"&gt;
+        &lt;property name="key"&gt;&lt;value&gt;springRocks&lt;/value&gt;&lt;/property&gt;
+        &lt;/bean&gt;
+        
+    </programlisting>Don't forget to add your
+        <literal>RememberMeServices</literal> implementation to your
+        <literal>AuthenticationProcessingFilter.setRememberMeServices()</literal>
+        property, include the
+        <literal>RememberMeAuthenticationProvider</literal> in your
+        <literal>AuthenticationManager.setProviders()</literal> list, and add
+        a call to <literal>RememberMeProcessingFilter</literal> into your
+        <literal>FilterChainProxy</literal> (typically immediately after your
+        <literal>AuthenticationProcessingFilter</literal>)</para>
+</sect1>
+</chapter>

src/docbkx/resources/css/html.css

@@ -0,0 +1,421 @@
+body {
+    text-align: justify;
+    margin-right: 2em;
+    margin-left: 2em;
+}
+
+a,
+    a[accesskey^
+
+=
+"h"
+]
+,
+a[accesskey^
+
+=
+"n"
+]
+,
+a[accesskey^
+
+=
+"u"
+]
+,
+a[accesskey^
+
+=
+"p"
+]
+{
+font-family: Verdana, Arial, helvetica, sans-serif
+
+;
+font-size:
+
+12
+px
+
+;
+color: #003399
+
+;
+}
+
+a:active {
+    color: #003399;
+}
+
+a:visited {
+    color: #888888;
+}
+
+p {
+    font-family: Verdana, Arial, sans-serif;
+}
+
+dt {
+    font-family: Verdana, Arial, sans-serif;
+    font-size: 12px;
+}
+
+p, dl, dt, dd, blockquote {
+    color: #000000;
+    margin-bottom: 3px;
+    margin-top: 3px;
+    padding-top: 0px;
+}
+
+ol, ul, p {
+    margin-top: 6px;
+    margin-bottom: 6px;
+}
+
+p, blockquote {
+    font-size: 90%;
+}
+
+p.releaseinfo {
+    font-size: 100%;
+    font-weight: bold;
+    font-family: Verdana, Arial, helvetica, sans-serif;
+    padding-top: 10px;
+}
+
+p.pubdate {
+    font-size: 120%;
+    font-weight: bold;
+    font-family: Verdana, Arial, helvetica, sans-serif;
+}
+
+td {
+    font-size: 80%;
+}
+
+td, th, span {
+    color: #000000;
+}
+
+td[width^
+
+=
+"40%"
+]
+{
+font-family: Verdana, Arial, helvetica, sans-serif
+
+;
+font-size:
+
+12
+px
+
+;
+color: #003399
+
+;
+}
+
+table[summary^
+
+=
+"Navigation header"
+]
+tbody tr th[colspan^
+
+=
+"3"
+]
+{
+font-family: Verdana, Arial, helvetica, sans-serif
+
+;
+}
+
+blockquote {
+    margin-right: 0px;
+}
+
+h1, h2, h3, h4, h6, H6 {
+    color: #000000;
+    font-weight: 500;
+    margin-top: 0px;
+    padding-top: 14px;
+    font-family: Verdana, Arial, helvetica, sans-serif;
+    margin-bottom: 0px;
+}
+
+h2.title {
+    font-weight: 800;
+    margin-bottom: 8px;
+}
+
+h2.subtitle {
+    font-weight: 800;
+    margin-bottom: 20px;
+}
+
+.firstname, .surname {
+    font-size: 12px;
+    font-family: Verdana, Arial, helvetica, sans-serif;
+}
+
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+    border: 1px black;
+    empty-cells: hide;
+    margin: 10px 0px 30px 50px;
+    width: 90%;
+}
+
+div.table {
+    margin: 30px 0px 30px 0px;
+    border: 1px dashed gray;
+    padding: 10px;
+}
+
+div .table-contents table {
+    border: 1px solid black;
+}
+
+div.table > p.title {
+    padding-left: 10px;
+}
+
+table[summary^
+
+=
+"Navigation footer"
+]
+{
+border-collapse: collapse
+
+;
+border-spacing:
+
+0
+;
+border:
+
+1
+px black
+
+;
+empty-cells: hide
+
+;
+margin:
+
+0
+px
+
+;
+width:
+
+100
+%
+;
+}
+
+table[summary^
+
+=
+"Note"
+]
+,
+table[summary^
+
+=
+"Warning"
+]
+,
+table[summary^
+
+=
+"Tip"
+]
+{
+border-collapse: collapse
+
+;
+border-spacing:
+
+0
+;
+border:
+
+1
+px black
+
+;
+empty-cells: hide
+
+;
+margin:
+
+10
+px
+
+0
+px
+
+10
+px
+
+-
+20
+px
+
+;
+width:
+
+100
+%
+;
+}
+
+td {
+    padding: 4pt;
+    font-family: Verdana, Arial, helvetica, sans-serif;
+}
+
+div.warning TD {
+    text-align: justify;
+}
+
+h1 {
+    font-size: 150%;
+}
+
+h2 {
+    font-size: 110%;
+}
+
+h3 {
+    font-size: 100%;
+    font-weight: bold;
+}
+
+h4 {
+    font-size: 90%;
+    font-weight: bold;
+}
+
+h5 {
+    font-size: 90%;
+    font-style: italic;
+}
+
+h6 {
+    font-size: 100%;
+    font-style: italic;
+}
+
+tt {
+    font-size: 110%;
+    font-family: "Courier New", Courier, monospace;
+    color: #000000;
+}
+
+.navheader, .navfooter {
+    border: none;
+}
+
+div.navfooter table {
+    border: dashed gray;
+    border-width: 1px 1px 1px 1px;
+    background-color: #cde48d;
+}
+
+pre {
+    font-size: 110%;
+    padding: 5px;
+    border-style: solid;
+    border-width: 1px;
+    border-color: #CCCCCC;
+    background-color: #f3f5e9;
+}
+
+ul, ol, li {
+    list-style: disc;
+}
+
+hr {
+    width: 100%;
+    height: 1px;
+    background-color: #CCCCCC;
+    border-width: 0px;
+    padding: 0px;
+}
+
+.variablelist {
+    padding-top: 10px;
+    padding-bottom: 10px;
+    margin: 0;
+}
+
+.term {
+    font-weight: bold;
+}
+
+.mediaobject {
+    padding-top: 30px;
+    padding-bottom: 30px;
+}
+
+.legalnotice {
+    font-family: Verdana, Arial, helvetica, sans-serif;
+    font-size: 12px;
+    font-style: italic;
+}
+
+.sidebar {
+    float: right;
+    margin: 10px 0px 10px 30px;
+    padding: 10px 20px 20px 20px;
+    width: 33%;
+    border: 1px solid black;
+    background-color: #F4F4F4;
+    font-size: 14px;
+}
+
+.property {
+    font-family: "Courier New", Courier, monospace;
+}
+
+a code {
+    font-family: Verdana, Arial, monospace;
+    font-size: 12px;
+}
+
+td code {
+    font-size: 110%;
+}
+
+div.note * td,
+    div.tip * td,
+    div.warning * td,
+    div.calloutlist * td {
+    text-align: justify;
+    font-size: 100%;
+}
+
+.programlisting .interfacename,
+    .programlisting .literal,
+    .programlisting .classname {
+    font-size: 95%;
+}
+
+.title .interfacename,
+    .title .literal,
+    .title .classname {
+    font-size: 130%;
+}
+
+/* everything in a <lineannotation/> is displayed in a coloured, comment-like font */
+.programlisting * .lineannotation,
+    .programlisting * .lineannotation * {
+    color: green;
+}

src/docbkx/resources/xsl/spring-security-docbook-fopdf.xsl → src/docbkx/resources/xsl/fopdf.xsl

@@ -1,66 +1,55 @@
-<?xml version="1.0"?>
-
-<!--
-
-    This is the XSL FO (PDF) stylesheet for the Spring Security Reference Guide.
-
-    Thanks are due to the Spring Project and Christian Bauer of the Hibernate project team for writing the original
-    stylesheet upon which this one is based. And to the Nuxeo team for further modifications.
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+
+    This is the XSL FO (PDF) stylesheet for the Spring reference
+    documentation.
+    
+    Thanks are due to Christian Bauer of the Hibernate project
+    team for writing the original stylesheet upon which this one
+    is based.
 -->
-
-<!DOCTYPE xsl:stylesheet [
-    <!ENTITY copyright "&#xA9;">
-]>
-
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-                version="1.0"
-                xmlns="http://www.w3.org/TR/xhtml1/transitional"
                 xmlns:fo="http://www.w3.org/1999/XSL/Format"
-                exclude-result-prefixes="#default">
-
+                version="1.0">
 
-<xsl:import href="urn:docbkx:stylesheet"/>
 
+    <xsl:import href="urn:docbkx:stylesheet"/>
 
-
-
-<!--###################################################
-                   Custom Title Page
-    ###################################################-->
+    <!--###################################################
+                  Custom Title Page
+   ################################################### -->
 
     <xsl:template name="book.titlepage.recto">
         <fo:block>
             <fo:table table-layout="fixed" width="175mm">
-                <fo:table-column column-width="175mm"/>x
+                <fo:table-column column-width="175mm"/>
                 <fo:table-body>
                     <fo:table-row>
                         <fo:table-cell text-align="center">
                             <fo:block>
-                                <fo:external-graphic src="./src/docbook/resources/images/logo.gif"/>
-                            </fo:block>
-                            <fo:block font-family="Helvetica" font-size="32pt"
-                                      font-weight="bold" padding-before="60mm">
-                                <xsl:value-of select="bookinfo/title"/>
+                                <fo:block font-family="Helvetica" font-size="24pt" padding-before="10mm">
+                                    <xsl:value-of select="bookinfo/title"/>
+                                </fo:block>
                             </fo:block>
-                            <fo:block font-family="Helvetica" font-size="24pt" padding-before="5mm">
+                            <fo:block font-family="Helvetica" font-size="22pt" padding-before="10mm">
                                 <xsl:value-of select="bookinfo/subtitle"/>
                             </fo:block>
-                            <fo:block font-family="Helvetica" font-size="16pt" padding="5mm">
+                            <fo:block font-family="Helvetica" font-size="12pt" padding="10mm">
                                 <xsl:value-of select="bookinfo/releaseinfo"/>
                             </fo:block>
                         </fo:table-cell>
                     </fo:table-row>
                     <fo:table-row>
                         <fo:table-cell text-align="center">
-                            <fo:block font-family="Helvetica" font-size="14pt" padding-before="10mm">
+                            <fo:block font-family="Helvetica" font-size="14pt" padding="10mm">
                                 <xsl:value-of select="bookinfo/pubdate"/>
                             </fo:block>
                         </fo:table-cell>
                     </fo:table-row>
                     <fo:table-row>
                         <fo:table-cell text-align="center">
-                            <fo:block font-family="Helvetica" font-size="14pt" padding-before="10mm">
-                             <!--   <xsl:text>Copyright &copyright; 2000-2007. </xsl:text> -->
+                            <fo:block font-family="Helvetica" font-size="12pt" padding="10mm">
+                                <xsl:text>Copyright &#xA9; 2005-2007 </xsl:text>
                                 <xsl:for-each select="bookinfo/authorgroup/author">
                                     <xsl:if test="position() > 1">
                                         <xsl:text>, </xsl:text>
@@ -70,7 +59,7 @@
                                     <xsl:value-of select="surname"/>
                                 </xsl:for-each>
                             </fo:block>
-                            <fo:block font-family="Helvetica" font-size="10pt" padding="5mm">
+                            <fo:block font-family="Helvetica" font-size="10pt" padding="1mm">
                                 <xsl:value-of select="bookinfo/legalnotice"/>
                             </fo:block>
                         </fo:table-cell>
@@ -80,7 +69,7 @@
         </fo:block>
     </xsl:template>
 
-    <!-- Prevent blank pages in output-->
+    <!-- Prevent blank pages in output -->
     <xsl:template name="book.titlepage.before.verso">
     </xsl:template>
     <xsl:template name="book.titlepage.verso">
@@ -88,11 +77,11 @@
     <xsl:template name="book.titlepage.separator">
     </xsl:template>
 
-<!--###################################################
-                      Header
-    ###################################################-->
+    <!--###################################################
+                     Header
+   ################################################### -->
 
-    <!-- More space in the center header for long text-->
+    <!-- More space in the center header for long text -->
     <xsl:attribute-set name="header.content.properties">
         <xsl:attribute name="font-family">
             <xsl:value-of select="$body.font.family"/>
@@ -101,92 +90,93 @@
         <xsl:attribute name="margin-right">-5em</xsl:attribute>
     </xsl:attribute-set>
 
-<!--###################################################
-                      Custom Footer
-    ###################################################-->
-	<xsl:template name="footer.content">
-		<xsl:param name="pageclass" select="''" />
-		<xsl:param name="sequence" select="''" />
-		<xsl:param name="position" select="''" />
-		<xsl:param name="gentext-key" select="''" />
-		<xsl:variable name="Version">
-			<xsl:if test="//releaseinfo">
-				<xsl:text>Spring Security </xsl:text><xsl:value-of select="//releaseinfo" /><xsl:text></xsl:text>
-			</xsl:if>
-		</xsl:variable>
-		<xsl:choose>
-			<xsl:when test="$sequence='blank'">
-				<xsl:if test="$position = 'center'">
-					<xsl:value-of select="$Version" />
-				</xsl:if>
-			</xsl:when>
-			<!-- for double sided printing, print page numbers on alternating sides (of the page)-->
-			<xsl:when test="$double.sided != 0">
-				<xsl:choose>
-					<xsl:when test="$sequence = 'even' and $position='left'">
-						<fo:page-number />
-					</xsl:when>
-					<xsl:when test="$sequence = 'odd' and $position='right'">
-						<fo:page-number />
-					</xsl:when>
-					<xsl:when test="$position='center'">
-						<xsl:value-of select="$Version" />
-					</xsl:when>
-				</xsl:choose>
-			</xsl:when>
-			<!-- for single sided printing, print all page numbers on the right (of the page)-->
-			<xsl:when test="$double.sided = 0">
-				<xsl:choose>
-					<xsl:when test="$position='center'">
-						<xsl:value-of select="$Version" />
-					</xsl:when>
-					<xsl:when test="$position='right'">
-						<fo:page-number />
-					</xsl:when>
-				</xsl:choose>
-			</xsl:when>
-		</xsl:choose>
-	</xsl:template>
-
-
-<!--###################################################
-                      Extensions
-    ###################################################-->
-
-    <!-- These extensions are required for table printing and other stuff-->
+    <!--###################################################
+                     Custom Footer
+   ################################################### -->
+    <xsl:template name="footer.content">
+        <xsl:param name="pageclass" select="''"/>
+        <xsl:param name="sequence" select="''"/>
+        <xsl:param name="position" select="''"/>
+        <xsl:param name="gentext-key" select="''"/>
+        <xsl:variable name="Version">
+            <xsl:if test="//releaseinfo">
+                <xsl:text>Spring-WS (</xsl:text>
+                <xsl:value-of select="//releaseinfo"/>
+                <xsl:text>)</xsl:text>
+            </xsl:if>
+        </xsl:variable>
+        <xsl:choose>
+            <xsl:when test="$sequence='blank'">
+                <xsl:if test="$position = 'center'">
+                    <xsl:value-of select="$Version"/>
+                </xsl:if>
+            </xsl:when>
+            <!-- for double sided printing, print page numbers on alternating sides (of the page) -->
+            <xsl:when test="$double.sided != 0">
+                <xsl:choose>
+                    <xsl:when test="$sequence = 'even' and $position='left'">
+                        <fo:page-number/>
+                    </xsl:when>
+                    <xsl:when test="$sequence = 'odd' and $position='right'">
+                        <fo:page-number/>
+                    </xsl:when>
+                    <xsl:when test="$position='center'">
+                        <xsl:value-of select="$Version"/>
+                    </xsl:when>
+                </xsl:choose>
+            </xsl:when>
+            <!-- for single sided printing, print all page numbers on the right (of the page) -->
+            <xsl:when test="$double.sided = 0">
+                <xsl:choose>
+                    <xsl:when test="$position='center'">
+                        <xsl:value-of select="$Version"/>
+                    </xsl:when>
+                    <xsl:when test="$position='right'">
+                        <fo:page-number/>
+                    </xsl:when>
+                </xsl:choose>
+            </xsl:when>
+        </xsl:choose>
+    </xsl:template>
+
+    <!--###################################################
+                     Extensions
+   ################################################### -->
+
+    <!-- These extensions are required for table printing and other stuff -->
     <xsl:param name="use.extensions">1</xsl:param>
-    <xsl:param name="tablecolumns.extension">1</xsl:param>
+    <xsl:param name="tablecolumns.extension">0</xsl:param>
     <xsl:param name="callout.extensions">1</xsl:param>
-    <!-- FOP provide only PDF Bookmarks at the moment-->
+    <!-- FOP provide only PDF Bookmarks at the moment -->
     <xsl:param name="fop.extensions">1</xsl:param>
 
-<!--###################################################
-                      Table Of Contents
-    ###################################################-->
+    <!--###################################################
+                     Table Of Contents
+   ################################################### -->
 
-    <!-- Generate the TOCs for named components only-->
+    <!-- Generate the TOCs for named components only -->
     <xsl:param name="generate.toc">
-        book toc,title
+        book toc
     </xsl:param>
 
-    <!-- Show only Sections up to level 3 in the TOCs-->
+    <!-- Show only Sections up to level 3 in the TOCs -->
     <xsl:param name="toc.section.depth">2</xsl:param>
 
     <!-- Dot and Whitespace as separator in TOC between Label and Title-->
     <xsl:param name="autotoc.label.separator" select="'.  '"/>
 
 
-<!--###################################################
-                   Paper & Page Size
-    ###################################################-->
+    <!--###################################################
+                  Paper & Page Size
+   ################################################### -->
 
-    <!-- Paper type, no headers on blank pages, no double sided printing-->
+    <!-- Paper type, no headers on blank pages, no double sided printing -->
     <xsl:param name="paper.type" select="'A4'"/>
     <xsl:param name="double.sided">0</xsl:param>
     <xsl:param name="headers.on.blank.pages">0</xsl:param>
     <xsl:param name="footers.on.blank.pages">0</xsl:param>
 
-    <!-- Space between paper border and content (chaotic stuff, don't touch)-->
+    <!-- Space between paper border and content (chaotic stuff, don't touch) -->
     <xsl:param name="page.margin.top">5mm</xsl:param>
     <xsl:param name="region.before.extent">10mm</xsl:param>
     <xsl:param name="body.margin.top">10mm</xsl:param>
@@ -198,43 +188,40 @@
     <xsl:param name="page.margin.outer">18mm</xsl:param>
     <xsl:param name="page.margin.inner">18mm</xsl:param>
 
-    <!-- No intendation of Titles-->
+    <!-- No intendation of Titles -->
     <xsl:param name="title.margin.left">0pc</xsl:param>
 
+    <!--###################################################
+                  Fonts & Styles
+   ################################################### -->
 
-<!--###################################################
-                   Fonts & Styles
-    ###################################################-->
-
-    <!-- Justified text and no hyphenation-->
+    <!-- Left aligned text and no hyphenation -->
     <xsl:param name="alignment">justify</xsl:param>
     <xsl:param name="hyphenate">false</xsl:param>
 
-    <!-- Default Font size-->
-    <xsl:param name="body.font.master">12</xsl:param>
+    <!-- Default Font size -->
+    <xsl:param name="body.font.master">11</xsl:param>
     <xsl:param name="body.font.small">8</xsl:param>
 
-    <!--xsl:param name="body.font.family">MinionPro</xsl:param-->
-
-    <!-- Line height in body text-->
-    <xsl:param name="line-height">1.3</xsl:param>
+    <!-- Line height in body text -->
+    <xsl:param name="line-height">1.4</xsl:param>
 
-    <!-- Monospaced fonts are smaller than regular text-->
+    <!-- Monospaced fonts are smaller than regular text -->
     <xsl:attribute-set name="monospace.properties">
         <xsl:attribute name="font-family">
             <xsl:value-of select="$monospace.font.family"/>
         </xsl:attribute>
-        <xsl:attribute name="font-size">0.7em</xsl:attribute>
+        <xsl:attribute name="font-size">0.8em</xsl:attribute>
     </xsl:attribute-set>
 
-<!--###################################################
-                   Tables
-    ###################################################-->
+    <!--###################################################
+                  Tables
+   ################################################### -->
 
-    <!-- The table width should be adapted to the paper size-->
+    <!-- The table width should be adapted to the paper size -->
     <xsl:param name="default.table.width">17.4cm</xsl:param>
 
-    <!-- Some padding inside tables-->
+    <!-- Some padding inside tables -->
     <xsl:attribute-set name="table.cell.padding">
         <xsl:attribute name="padding-left">4pt</xsl:attribute>
         <xsl:attribute name="padding-right">4pt</xsl:attribute>
@@ -242,24 +229,24 @@
         <xsl:attribute name="padding-bottom">4pt</xsl:attribute>
     </xsl:attribute-set>
 
-    <!-- Only hairlines as frame and cell borders in tables-->
+    <!-- Only hairlines as frame and cell borders in tables -->
     <xsl:param name="table.frame.border.thickness">0.1pt</xsl:param>
     <xsl:param name="table.cell.border.thickness">0.1pt</xsl:param>
 
-<!--###################################################
-                         Labels
-    ###################################################-->
+    <!--###################################################
+                        Labels
+   ################################################### -->
 
-    <!-- Label Chapters and Sections (numbering)-->
+    <!-- Label Chapters and Sections (numbering) -->
     <xsl:param name="chapter.autolabel">1</xsl:param>
     <xsl:param name="section.autolabel" select="1"/>
     <xsl:param name="section.label.includes.component.label" select="1"/>
 
-<!--###################################################
-                         Titles
-    ###################################################-->
+    <!--###################################################
+                        Titles
+   ################################################### -->
 
-    <!-- Chapter title size-->
+    <!-- Chapter title size -->
     <xsl:attribute-set name="chapter.titlepage.recto.style">
         <xsl:attribute name="text-align">left</xsl:attribute>
         <xsl:attribute name="font-weight">bold</xsl:attribute>
@@ -269,18 +256,18 @@
         </xsl:attribute>
     </xsl:attribute-set>
 
-    <!-- Why is the font-size for chapters hardcoded in the XSL FO templates?
-        Let's remove it, so this sucker can use our attribute-set only...-->
+    <!-- Why is the font-size for chapters hardcoded in the XSL FO templates? 
+        Let's remove it, so this sucker can use our attribute-set only... -->
     <xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
         <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format"
                   xsl:use-attribute-sets="chapter.titlepage.recto.style">
             <xsl:call-template name="component.title">
                 <xsl:with-param name="node" select="ancestor-or-self::chapter[1]"/>
             </xsl:call-template>
-            </fo:block>
+        </fo:block>
     </xsl:template>
 
-    <!-- Sections 1, 2 and 3 titles have a small bump factor and padding-->
+    <!-- Sections 1, 2 and 3 titles have a small bump factor and padding -->
     <xsl:attribute-set name="section.title.level1.properties">
         <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
         <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
@@ -318,7 +305,7 @@
         <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
     </xsl:attribute-set>
 
-    <!-- Titles of formal objects (tables, examples, ...)-->
+    <!-- Titles of formal objects (tables, examples, ...) -->
     <xsl:attribute-set name="formal.title.properties" use-attribute-sets="normal.para.spacing">
         <xsl:attribute name="font-weight">bold</xsl:attribute>
         <xsl:attribute name="font-size">
@@ -331,11 +318,11 @@
         <xsl:attribute name="space-after.maximum">0.8em</xsl:attribute>
     </xsl:attribute-set>
 
-<!--###################################################
-                      Programlistings
-    ###################################################-->
+    <!--###################################################
+                     Programlistings
+   ################################################### -->
 
-    <!-- Verbatim text formatting (programlistings)-->
+    <!-- Verbatim text formatting (programlistings) -->
     <xsl:attribute-set name="monospace.verbatim.properties">
         <xsl:attribute name="font-size">
             <xsl:value-of select="$body.font.small * 1.0"/>
@@ -358,39 +345,36 @@
         <xsl:attribute name="margin-right">0.5em</xsl:attribute>
     </xsl:attribute-set>
 
-    <!-- Shade (background) programlistings-->
+    <!-- Shade (background) programlistings -->
     <xsl:param name="shade.verbatim">1</xsl:param>
     <xsl:attribute-set name="shade.verbatim.style">
-        <xsl:attribute name="background-color">#EEEEEE</xsl:attribute>
-        <xsl:attribute name="border-color">#CCCCCC</xsl:attribute>
+        <xsl:attribute name="background-color">#F0F0F0</xsl:attribute>
     </xsl:attribute-set>
 
-<!--###################################################
-                         Callouts
-    ###################################################-->
+    <!--###################################################
+                        Callouts
+   ################################################### -->
 
-    <!-- Use images for callouts instead of (1) (2) (3)-->
+    <!-- Use images for callouts instead of (1) (2) (3) -->
     <xsl:param name="callout.graphics">0</xsl:param>
     <xsl:param name="callout.unicode">1</xsl:param>
 
-    <!-- Place callout marks at this column in annotated areas-->
+    <!-- Place callout marks at this column in annotated areas -->
     <xsl:param name="callout.defaultcolumn">90</xsl:param>
 
-<!--###################################################
-                       Admonitions
-    ###################################################-->
+    <!--###################################################
+                      Admonitions
+   ################################################### -->
 
-    <!-- Use nice graphics for admonitions-->
-    <xsl:param name="admon.graphics">1</xsl:param>
-    <xsl:param name="admon.graphics.path">resources/images/admons/</xsl:param>
+    <!-- Use nice graphics for admonitions -->
+    <xsl:param name="admon.graphics">'1'</xsl:param>
+    <!--  <xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param> -->
 
-    <!--xsl:param name="admon.graphics.path">&admon_gfx_path;</xsl:param-->
+    <!--###################################################
+                         Misc
+   ################################################### -->
 
-<!--###################################################
-                          Misc
-    ###################################################-->
-
-    <!-- Placement of titles-->
+    <!-- Placement of titles -->
     <xsl:param name="formal.title.placement">
         figure after
         example before
@@ -399,37 +383,36 @@
         procedure before
     </xsl:param>
 
-    <!-- Format Variable Lists as Blocks (prevents horizontal overflow)-->
+    <!-- Format Variable Lists as Blocks (prevents horizontal overflow) -->
     <xsl:param name="variablelist.as.blocks">1</xsl:param>
 
-    <!-- The horrible list spacing problems-->
+    <!-- The horrible list spacing problems -->
     <xsl:attribute-set name="list.block.spacing">
-        <xsl:attribute name="space-before.optimum">-0.3em</xsl:attribute>
-        <xsl:attribute name="space-before.minimum">-0.5em</xsl:attribute>
-        <xsl:attribute name="space-before.maximum">0em</xsl:attribute>
-        <xsl:attribute name="space-after.optimum">0.8em</xsl:attribute>
-        <xsl:attribute name="space-after.minimum">0.4em</xsl:attribute>
-        <xsl:attribute name="space-after.maximum">1.2em</xsl:attribute>
-        <xsl:attribute name="margin-left">1.6em</xsl:attribute>
+        <xsl:attribute name="space-before.optimum">0.8em</xsl:attribute>
+        <xsl:attribute name="space-before.minimum">0.8em</xsl:attribute>
+        <xsl:attribute name="space-before.maximum">0.8em</xsl:attribute>
+        <xsl:attribute name="space-after.optimum">0.1em</xsl:attribute>
+        <xsl:attribute name="space-after.minimum">0.1em</xsl:attribute>
+        <xsl:attribute name="space-after.maximum">0.1em</xsl:attribute>
     </xsl:attribute-set>
 
-<!--###################################################
-              colored and hyphenated links
-    ###################################################-->
-	<xsl:template match="ulink">
-	<fo:basic-link external-destination="{@url}"
-			xsl:use-attribute-sets="xref.properties"
-			text-decoration="underline"
-			color="blue">
-			<xsl:choose>
-			<xsl:when test="count(child::node())=0">
-			<xsl:value-of select="@url"/>
-			</xsl:when>
-			<xsl:otherwise>
-			<xsl:apply-templates/>
-			</xsl:otherwise>
-			</xsl:choose>
-			</fo:basic-link>
-	</xsl:template>
+    <!--###################################################
+             colored and hyphenated links
+   ################################################### -->
+    <xsl:template match="ulink">
+        <fo:basic-link external-destination="{@url}"
+                       xsl:use-attribute-sets="xref.properties"
+                       text-decoration="underline"
+                       color="blue">
+            <xsl:choose>
+                <xsl:when test="count(child::node())=0">
+                    <xsl:value-of select="@url"/>
+                </xsl:when>
+                <xsl:otherwise>
+                    <xsl:apply-templates/>
+                </xsl:otherwise>
+            </xsl:choose>
+        </fo:basic-link>
+    </xsl:template>
 
 </xsl:stylesheet>

src/docbkx/resources/xsl/spring-security-docbook-html.xsl → src/docbkx/resources/xsl/html.xsl

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!--
-    This is the XSL HTML configuration file for the Spring Security
+<!-- 
+    This is the XSL HTML configuration file for the Spring
     Reference Documentation.
 -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
@@ -17,11 +17,9 @@
 
     <!-- These extensions are required for table printing and other stuff -->
     <xsl:param name="use.extensions">1</xsl:param>
-    <xsl:param name="tablecolumns.extension">1</xsl:param>
-    <xsl:param name="callout.extension">1</xsl:param>
+    <xsl:param name="tablecolumns.extension">0</xsl:param>
+    <xsl:param name="callout.extensions">1</xsl:param>
     <xsl:param name="graphicsize.extension">0</xsl:param>
-    <xsl:param name="keep.relative.image.uris" select="1"></xsl:param>
-    <xsl:param name="img.src.path">./</xsl:param>
 
     <!--###################################################
                      Table Of Contents
@@ -29,16 +27,11 @@
 
     <!-- Generate the TOCs for named components only -->
     <xsl:param name="generate.toc">
-      book toc,title
-      chapter toc
-      article/appendix toc
-      qandadiv nop
-      qandaset toc
+        book toc
     </xsl:param>
 
-    <!-- Show only Sections up to level 2 in the TOCs -->
-    <xsl:param name="toc.section.depth">2</xsl:param>
-    <xsl:param name="generate.section.toc.level" select="0"></xsl:param>
+    <!-- Show only Sections up to level 3 in the TOCs -->
+    <xsl:param name="toc.section.depth">3</xsl:param>
 
     <!--###################################################
                         Labels
@@ -46,17 +39,15 @@
 
     <!-- Label Chapters and Sections (numbering) -->
     <xsl:param name="chapter.autolabel">1</xsl:param>
-    <xsl:param name="chapter.label.includes.component.label">1</xsl:param>
-    <xsl:param name="section.autolabel">1</xsl:param>
-    <xsl:param name="section.label.includes.component.label">1</xsl:param>
-    <xsl:param name="section.autolabel.max.depth">3</xsl:param>
+    <xsl:param name="section.autolabel" select="1"/>
+    <xsl:param name="section.label.includes.component.label" select="1"/>
 
     <!--###################################################
                         Callouts
    ################################################### -->
 
     <!-- Use images for callouts instead of (1) (2) (3) -->
-    <xsl:param name="callout.graphics">1</xsl:param>
+    <xsl:param name="callout.graphics">0</xsl:param>
 
     <!-- Place callout marks at this column in annotated areas -->
     <xsl:param name="callout.defaultcolumn">90</xsl:param>
@@ -73,11 +64,11 @@
    ################################################### -->
     <!-- Placement of titles -->
     <xsl:param name="formal.title.placement">
-      figure after
-      example after
-      equation after
-      table after
-      procedure after
+        figure after
+        example before
+        equation before
+        table before
+        procedure before
     </xsl:param>
     <xsl:template match="author" mode="titlepage.mode">
         <xsl:if test="name(preceding-sibling::*[1]) = 'author'">
@@ -97,24 +88,4 @@
         </div>
     </xsl:template>
 
-    <!--###################################################
-                     Headers and Footers
-    ################################################### -->
-    <!--  banner across the top of each page -->
-<!--
-    <xsl:template name="user.header.content">
-        <div id="banner">
-            <a style="border:none;" href="http://nuxeo.org/"
-               title="Spring Security - Reference Guide">
-                <img style="border:none;"
-                  width="455" height="69" alt="Spring Security Reference Documentation"
-                  src="images/logo.jpg"/>
-            </a>
-        </div>
-    </xsl:template>
-
-    <xsl:template name="user.footer.content">
-      <p class="copyright">&#x00A9; 2001-2007 Nuxeo SAS.</p>
-    </xsl:template>
--->
 </xsl:stylesheet>

src/docbkx/resources/xsl/html_chunk.xsl

@@ -0,0 +1,208 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+    This is the XSL HTML configuration file for the Spring Reference Documentation.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"
+                version="1.0">
+
+    <xsl:import href="urn:docbkx:stylesheet"/>
+    <!--###################################################
+                     HTML Settings
+    ################################################### -->
+    <xsl:param name="chunk.section.depth">'5'</xsl:param>
+    <xsl:param name="use.id.as.filename">'1'</xsl:param>
+    <!-- These extensions are required for table printing and other stuff -->
+    <xsl:param name="use.extensions">1</xsl:param>
+    <xsl:param name="tablecolumns.extension">0</xsl:param>
+    <xsl:param name="callout.extensions">1</xsl:param>
+    <xsl:param name="graphicsize.extension">0</xsl:param>
+    <!--###################################################
+                      Table Of Contents
+    ################################################### -->
+    <!-- Generate the TOCs for named components only -->
+    <xsl:param name="generate.toc">
+        book toc
+    </xsl:param>
+    <!-- Show only Sections up to level 3 in the TOCs -->
+    <xsl:param name="toc.section.depth">3</xsl:param>
+    <!--###################################################
+                         Labels
+    ################################################### -->
+    <!-- Label Chapters and Sections (numbering) -->
+    <xsl:param name="chapter.autolabel">1</xsl:param>
+    <xsl:param name="section.autolabel" select="1"/>
+    <xsl:param name="section.label.includes.component.label" select="1"/>
+    <!--###################################################
+                         Callouts
+    ################################################### -->
+    <!-- Place callout marks at this column in annotated areas -->
+    <xsl:param name="callout.graphics">1</xsl:param>
+    <xsl:param name="callout.defaultcolumn">90</xsl:param>
+    <!--###################################################
+                          Misc
+    ################################################### -->
+    <!-- Placement of titles -->
+    <xsl:param name="formal.title.placement">
+        figure after
+        example before
+        equation before
+        table before
+        procedure before
+    </xsl:param>
+    <xsl:template match="author" mode="titlepage.mode">
+        <xsl:if test="name(preceding-sibling::*[1]) = 'author'">
+            <xsl:text>, </xsl:text>
+        </xsl:if>
+        <span class="{name(.)}">
+            <xsl:call-template name="person.name"/>
+            <xsl:apply-templates mode="titlepage.mode" select="./contrib"/>
+            <xsl:apply-templates mode="titlepage.mode" select="./affiliation"/>
+        </span>
+    </xsl:template>
+    <xsl:template match="authorgroup" mode="titlepage.mode">
+        <div class="{name(.)}">
+            <h2>Authors</h2>
+            <p/>
+            <xsl:apply-templates mode="titlepage.mode"/>
+        </div>
+    </xsl:template>
+    <!--###################################################
+                     Headers and Footers
+    ################################################### -->
+    <!-- let's have a Spring and SpringSource banner across the top of each page -->
+    <xsl:template name="user.header.navigation">
+        <div style="background-color:white;border:none;height:73px;border:1px solid black;">
+            <a style="border:none;" href="http://static.springframework.org/spring-ws/site/"
+               title="The Spring Framework - Spring Web Services">
+                <img style="border:none;" src="images/xdev-spring_logo.jpg"/>
+            </a>
+            <a style="border:none;" href="http://www.springsource.com/" title="SpringSource">
+                <img style="border:none;position:absolute;padding-top:5px;right:42px;" src="images/s2_box_logo.png"/>
+            </a>
+        </div>
+    </xsl:template>
+    <!-- no other header navigation (prev, next, etc.) -->
+    <xsl:template name="header.navigation"/>
+    <xsl:param name="navig.showtitles">1</xsl:param>
+    <!-- let's have a 'Sponsored by SpringSource' strapline (or somesuch) across the bottom of each page -->
+    <xsl:template name="footer.navigation">
+        <xsl:param name="prev" select="/foo"/>
+        <xsl:param name="next" select="/foo"/>
+        <xsl:param name="nav.context"/>
+        <xsl:variable name="home" select="/*[1]"/>
+        <xsl:variable name="up" select="parent::*"/>
+        <xsl:variable name="row1" select="count($prev) &gt; 0
+                                        or count($up) &gt; 0
+                                        or count($next) &gt; 0"/>
+        <xsl:variable name="row2" select="($prev and $navig.showtitles != 0)
+                                        or (generate-id($home) != generate-id(.)
+                                            or $nav.context = 'toc')
+                                        or ($chunk.tocs.and.lots != 0
+                                            and $nav.context != 'toc')
+                                        or ($next and $navig.showtitles != 0)"/>
+        <xsl:if test="$suppress.navigation = '0' and $suppress.footer.navigation = '0'">
+            <div class="navfooter">
+                <xsl:if test="$footer.rule != 0">
+                    <hr/>
+                </xsl:if>
+                <xsl:if test="$row1 or $row2">
+                    <table width="100%" summary="Navigation footer">
+                        <xsl:if test="$row1">
+                            <tr>
+                                <td width="40%" align="left">
+                                    <xsl:if test="count($prev)>0">
+                                        <a accesskey="p">
+                                            <xsl:attribute name="href">
+                                                <xsl:call-template name="href.target">
+                                                    <xsl:with-param name="object" select="$prev"/>
+                                                </xsl:call-template>
+                                            </xsl:attribute>
+                                            <xsl:call-template name="navig.content">
+                                                <xsl:with-param name="direction" select="'prev'"/>
+                                            </xsl:call-template>
+                                        </a>
+                                    </xsl:if>
+                                    <xsl:text>&#160;</xsl:text>
+                                </td>
+
+                                <td width="20%" align="center">
+                                    <xsl:choose>
+                                        <xsl:when test="$home != . or $nav.context = 'toc'">
+                                            <a accesskey="h">
+                                                <xsl:attribute name="href">
+                                                    <xsl:call-template name="href.target">
+                                                        <xsl:with-param name="object" select="$home"/>
+                                                    </xsl:call-template>
+                                                </xsl:attribute>
+                                                <xsl:call-template name="navig.content">
+                                                    <xsl:with-param name="direction" select="'home'"/>
+                                                </xsl:call-template>
+                                            </a>
+                                            <xsl:if test="$chunk.tocs.and.lots != 0 and $nav.context != 'toc'">
+                                                <xsl:text>&#160;|&#160;</xsl:text>
+                                            </xsl:if>
+                                        </xsl:when>
+                                        <xsl:otherwise>&#160;</xsl:otherwise>
+                                    </xsl:choose>
+                                    <xsl:if test="$chunk.tocs.and.lots != 0 and $nav.context != 'toc'">
+                                        <a accesskey="t">
+                                            <xsl:attribute name="href">
+                                                <xsl:apply-templates select="/*[1]" mode="recursive-chunk-filename">
+                                                    <xsl:with-param name="recursive" select="true()"/>
+                                                </xsl:apply-templates>
+                                                <xsl:text>-toc</xsl:text>
+                                                <xsl:value-of select="$html.ext"/>
+                                            </xsl:attribute>
+                                            <xsl:call-template name="gentext">
+                                                <xsl:with-param name="key" select="'nav-toc'"/>
+                                            </xsl:call-template>
+                                        </a>
+                                    </xsl:if>
+                                </td>
+                                <td width="40%" align="right">
+                                    <xsl:text>&#160;</xsl:text>
+                                    <xsl:if test="count($next)>0">
+                                        <a accesskey="n">
+                                            <xsl:attribute name="href">
+                                                <xsl:call-template name="href.target">
+                                                    <xsl:with-param name="object" select="$next"/>
+                                                </xsl:call-template>
+                                            </xsl:attribute>
+                                            <xsl:call-template name="navig.content">
+                                                <xsl:with-param name="direction" select="'next'"/>
+                                            </xsl:call-template>
+                                        </a>
+                                    </xsl:if>
+                                </td>
+                            </tr>
+                        </xsl:if>
+                        <xsl:if test="$row2">
+                            <tr>
+                                <td width="40%" align="left" valign="top">
+                                    <xsl:if test="$navig.showtitles != 0">
+                                        <xsl:apply-templates select="$prev" mode="object.title.markup"/>
+                                    </xsl:if>
+                                    <xsl:text>&#160;</xsl:text>
+                                </td>
+                                <td width="20%" align="center">
+                                    <span style="color:white;font-size:90%;">
+                                        <a href="http://www.springsource.com/"
+                                           title="SpringSource">Sponsored by SpringSource
+                                        </a>
+                                    </span>
+                                </td>
+                                <td width="40%" align="right" valign="top">
+                                    <xsl:text>&#160;</xsl:text>
+                                    <xsl:if test="$navig.showtitles != 0">
+                                        <xsl:apply-templates select="$next" mode="object.title.markup"/>
+                                    </xsl:if>
+                                </td>
+                            </tr>
+                        </xsl:if>
+                    </table>
+                </xsl:if>
+            </div>
+        </xsl:if>
+    </xsl:template>
+</xsl:stylesheet>

src/docbkx/runas-auth-provider.xml

@@ -0,0 +1,111 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">                         
+
+<chapter id="runas">
+    <title>Run-As Authentication Replacement</title>
+    
+    <sect1 id="runas-overview">
+        <title>Overview</title>
+        
+        <para>The <literal>AbstractSecurityInterceptor</literal> is able to
+            temporarily replace the <literal>Authentication</literal> object in
+            the <literal>SecurityContext</literal> and
+            <literal>SecurityContextHolder</literal> during the secure object
+            callback phase. This only occurs if the original
+            <literal>Authentication</literal> object was successfully processed by
+            the <literal>AuthenticationManager</literal> and
+            <literal>AccessDecisionManager</literal>. The
+            <literal>RunAsManager</literal> will indicate the replacement
+            <literal>Authentication</literal> object, if any, that should be used
+            during the <literal>SecurityInterceptorCallback</literal>.</para>
+        
+        <para>By temporarily replacing the <literal>Authentication</literal>
+            object during the secure object callback phase, the secured invocation
+            will be able to call other objects which require different
+            authentication and authorization credentials. It will also be able to
+            perform any internal security checks for specific
+            <literal>GrantedAuthority</literal> objects. Because Spring Security
+            provides a number of helper classes that automatically configure
+            remoting protocols based on the contents of the
+            <literal>SecurityContextHolder</literal>, these run-as replacements
+            are particularly useful when calling remote web services</para>
+    </sect1>
+    
+    <sect1 id="runas-config">
+        <title>Configuration</title>
+        
+        <para>A <literal>RunAsManager</literal> interface is provided by Acegi
+            Security:</para>
+        
+        <para><programlisting>public Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config);
+            public boolean supports(ConfigAttribute attribute);
+            public boolean supports(Class clazz);</programlisting></para>
+        
+        <para>The first method returns the <literal>Authentication</literal>
+            object that should replace the existing
+            <literal>Authentication</literal> object for the duration of the
+            method invocation. If the method returns <literal>null</literal>, it
+            indicates no replacement should be made. The second method is used by
+            the <literal>AbstractSecurityInterceptor</literal> as part of its
+            startup validation of configuration attributes. The
+            <literal>supports(Class)</literal> method is called by a security
+            interceptor implementation to ensure the configured
+            <literal>RunAsManager</literal> supports the type of secure object
+            that the security interceptor will present.</para>
+        
+        <para>One concrete implementation of a <literal>RunAsManager</literal>
+            is provided with Spring Security. The
+            <literal>RunAsManagerImpl</literal> class returns a replacement
+            <literal>RunAsUserToken</literal> if any
+            <literal>ConfigAttribute</literal> starts with
+            <literal>RUN_AS_</literal>. If any such
+            <literal>ConfigAttribute</literal> is found, the replacement
+            <literal>RunAsUserToken</literal> will contain the same principal,
+            credentials and granted authorities as the original
+            <literal>Authentication</literal> object, along with a new
+            <literal>GrantedAuthorityImpl</literal> for each
+            <literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each
+            new <literal>GrantedAuthorityImpl</literal> will be prefixed with
+            <literal>ROLE_</literal>, followed by the <literal>RUN_AS</literal>
+            <literal>ConfigAttribute</literal>. For example, a
+            <literal>RUN_AS_SERVER</literal> will result in the replacement
+            <literal>RunAsUserToken</literal> containing a
+            <literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para>
+        
+        <para>The replacement <literal>RunAsUserToken</literal> is just like
+            any other <literal>Authentication</literal> object. It needs to be
+            authenticated by the <literal>AuthenticationManager</literal>,
+            probably via delegation to a suitable
+            <literal>AuthenticationProvider</literal>. The
+            <literal>RunAsImplAuthenticationProvider</literal> performs such
+            authentication. It simply accepts as valid any
+            <literal>RunAsUserToken</literal> presented.</para>
+        
+        <para>To ensure malicious code does not create a
+            <literal>RunAsUserToken</literal> and present it for guaranteed
+            acceptance by the <literal>RunAsImplAuthenticationProvider</literal>,
+            the hash of a key is stored in all generated tokens. The
+            <literal>RunAsManagerImpl</literal> and
+            <literal>RunAsImplAuthenticationProvider</literal> is created in the
+            bean context with the same key:</para>
+        
+        <para><programlisting>
+            &lt;bean id="runAsManager" class="org.springframework.security.runas.RunAsManagerImpl"&gt;
+            &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
+            &lt;/bean&gt;
+            
+            &lt;bean id="runAsAuthenticationProvider"
+            class="org.springframework.security.runas.RunAsImplAuthenticationProvider"&gt;
+            &lt;property name="key"&gt;&lt;value&gt;my_run_as_password&lt;/value&gt;&lt;/property&gt;
+            &lt;/bean&gt;
+            
+        </programlisting></para>
+        
+        <para>By using the same key, each <literal>RunAsUserToken</literal>
+            can be validated it was created by an approved
+            <literal>RunAsManagerImpl</literal>. The
+            <literal>RunAsUserToken</literal> is immutable after creation for
+            security reasons</para>
+    </sect1>
+</chapter>

src/docbkx/samples.xml

@@ -0,0 +1,152 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="sample-apps">
+<title id="samples">Sample Applications</title>
+
+<sect1 id="contacts-sample">
+    <title id="contacts">Contacts</title>
+    
+    <para>Included with Spring Security is a very simple application that
+        can demonstrate the basic security facilities provided by the system
+        (and confirm your Container Adapter is properly configured if you're
+        using one).</para>
+    
+    <para>If you build from Subversion, the Contacts sample application
+        includes three deployable versions:
+        <literal>spring-security-sample-contacts-filter.war</literal> is
+        configured with the HTTP Session Authentication approach.
+        <literal>spring-security-sample-contacts-ca.war</literal> is
+        configured to use a Container Adapter. Finally,
+        <literal>spring-security-sample-contacts-cas.war</literal> is designed
+        to work with a JA-SIG CAS server. If you're just wanting to see how
+        the sample application works, please use
+        <literal><literal>spring-security-sample-contacts-filter.war</literal></literal>
+        as it does not require special configuration of your container. This
+        is also the artifact included in official release ZIPs.</para>
+    
+    <para>To deploy, simply copy the relevant WAR file from Spring
+        Security distribution into your container’s <literal>webapps</literal>
+        directory.</para>
+    
+    <para>After starting your container, check the application can load.
+        Visit
+        <literal>http://localhost:8080/spring-security-sample-contacts-filter</literal>
+        (or whichever URL is appropriate for your web container and the WAR
+        you deployed). A random contact should be displayed. Click "Refresh"
+        several times and you will see different contacts. The business method
+        that provides this random contact is not secured.</para>
+    
+    <para>Next, click "Debug". You will be prompted to authenticate, and a
+        series of usernames and passwords are suggested on that page. Simply
+        authenticate with any of these and view the resulting page. It should
+        contain a success message similar to the following:</para>
+    
+    <blockquote>
+        <para>Context on SecurityContextHolder is of type:
+            org.springframework.security.context.SecurityContextImpl</para>
+        
+        <para>The Context implements SecurityContext.</para>
+        
+        <para>Authentication object is of type:
+            org.springframework.security.adapters.PrincipalSpringSecurityUserToken</para>
+        
+        <para>Authentication object as a String:
+            org.springframework.security.adapters.PrincipalSpringSecurityUserToken@e9a7c2:
+            Username: rod; Password: [PROTECTED]; Authenticated: true; Granted
+            Authorities: ROLE_TELLER, ROLE_SUPERVISOR</para>
+        
+        <para>Authentication object holds the following granted
+            authorities:</para>
+        
+        <para>ROLE_TELLER (getAuthority(): ROLE_TELLER)</para>
+        
+        <para>ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)</para>
+        
+        <para>SUCCESS! Your [container adapter|web filter] appears to be
+            properly configured!</para>
+    </blockquote>
+    
+    <para>If you receive a different message, and deployed
+        <literal>spring-security-sample-contacts-ca.war</literal>, check you
+        have properly configured your Container Adapter as described elsewhere
+        in this reference guide.</para>
+    
+    <para>Once you successfully receive the above message, return to the
+        sample application's home page and click "Manage". You can then try
+        out the application. Notice that only the contacts available to the
+        currently logged on user are displayed, and only users with
+        <literal>ROLE_SUPERVISOR</literal> are granted access to delete their
+        contacts. Behind the scenes, the
+        <literal>MethodSecurityInterceptor</literal> is securing the business
+        objects. If you're using or
+        <literal>spring-security-sample-contacts-cas.war</literal>, the
+        <literal><literal>spring-security-sample-contacts-filter.war</literal></literal>
+        <literal>FilterSecurityInterceptor</literal> is also securing the HTTP
+        requests. If using either of these WARs, be sure to try visiting
+        <literal>http://localhost:8080/contacts/secure/super</literal>, which
+        will demonstrate access being denied by the
+        <literal>FilterSecurityInterceptor</literal>. Note the sample
+        application enables you to modify the access control lists associated
+        with different contacts. Be sure to give this a try and understand how
+        it works by reviewing the sample application's application context XML
+        files.</para>
+    
+    <para>The Contacts sample application also include a
+        <literal>client</literal> directory. Inside you will find a small
+        application that queries the backend business objects using several
+        web services protocols. This demonstrates how to use Spring Security
+        for authentication with Spring remoting protocols. To try this client,
+        ensure your servlet container is still running the Contacts sample
+        application, and then execute <literal>client rod koala</literal>. The
+        command-line parameters respectively represent the username to use,
+        and the password to use. Note that you may need to edit
+        <literal>client.properties</literal> to use a different target
+        URL.</para>
+</sect1>
+
+<sect1 id="tutorial-sample">
+    <title>Tutorial Sample</title>
+    
+    <para>Whilst the <link linkend="contacts-sample">Contacts
+        Sample</link> is quite advanced in that it illustrates the more
+        powerful features of domain object access control lists and so on,
+        sometimes you just want to start with a nice basic example. The
+        tutorial sample is intended to provide this for you.</para>
+    
+    <para>The compiled tutorial is included in the distribution ZIP file,
+        ready to be deployed into your web container. Authentication is
+        handled by the <link linkend="dao-provider">DaoAuthenticationProvider</link>, using the
+        <link linkend="in-memory-service">in-memory</link>
+        <literal>UserDetailsService</literal> that sources information from
+        the <literal>users.properties</literal> file located in the WAR's
+        <literal>/WEB-INF</literal> directory. The <link linkend="form">form-based</link> 
+        authentication mechanism is used, with the commonly-used 
+        <link linkend="remember-me">remember-me</link>
+        authentication provider used to automatically remember the login using
+        cookies.</para>
+    
+    <para>In terms of authorization, to keep things simple we've
+        configured the tutorial to only perform some basic <link
+            linkend="filter-invocation-authorization">web filter
+            authorization</link>. We've wired two common <link
+                linkend="pre-invocation">pre-invocation access decision voters</link>,
+        being the <literal>RoleVoter</literal> and
+        <literal>AuthenticatedVoter</literal>, such that
+        <literal>ROLE_*</literal> configuration attributes and
+        <literal>IS_AUTHENTICATED_*</literal> configuration attributes may be
+        used. Of course, it's extremely easy to add in other providers, with
+        most users probably starting with some services-layer security using
+        <link linkend="aop-alliance">MethodSecurityInterceptor</link>.</para>
+    
+    <para>We recommend you start with the tutorial sample, as the XML is
+        minimal and easy to follow. All of the needed <link
+            linkend="filters">filters</link> are configured properly, and using
+        best practise. Most importantly, you can easily this one XML file (and
+        its corresponding <literal>web.xml</literal> entries) to your existing
+        application. Only when this basic integration is achieved do we
+        suggest you attempt adding in method authorization or domain object
+        security.</para>
+</sect1>
+</chapter>

src/docbkx/secured-objects.xml

@@ -0,0 +1,519 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="secure-object-impls">
+  <title>Secure Object Implementations</title>
+
+  <sect1 id="aop-alliance">
+    <title>AOP Alliance (MethodInvocation) Security Interceptor</title>
+
+    <para>To secure <literal>MethodInvocation</literal>s, developers
+    simply add a properly configured
+    <literal>MethodSecurityInterceptor</literal> into the application
+    context. Next the beans requiring security are chained into the
+    interceptor. This chaining is accomplished using Spring’s
+    <literal>ProxyFactoryBean</literal> or
+    <literal>BeanNameAutoProxyCreator</literal>, as commonly used by many
+    other parts of Spring (refer to the sample application for examples).
+    Alternatively, Spring Security provides a
+    <literal>MethodDefinitionSourceAdvisor</literal> which may be used
+    with Spring's <literal>DefaultAdvisorAutoProxyCreator</literal> to
+    automatically chain the security interceptor in front of any beans
+    defined against the <literal>MethodSecurityInterceptor</literal>. The
+    <literal>MethodSecurityInterceptor</literal> itself is configured as
+    follows:</para>
+
+    <programlisting>&lt;bean id="bankManagerSecurity"
+        class="org.springframework.security.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
+&lt;property name="validateConfigAttributes"&gt;&lt;value&gt;true&lt;/value&gt;&lt;/property&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+&lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
+&lt;property name="afterInvocationManager"&gt;&lt;ref bean="afterInvocationManager"/&gt;&lt;/property&gt;
+&lt;property name="objectDefinitionSource"&gt;
+&lt;value&gt;
+        org.springframework.security.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
+        org.springframework.security.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
+        &lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting>
+
+    <para>As shown above, the <literal>MethodSecurityInterceptor</literal>
+    is configured with a reference to an
+    <literal>AuthenticationManager</literal>,
+    <literal>AccessDecisionManager</literal> and
+    <literal>RunAsManager</literal>, which are each discussed in separate
+    sections below. In this case we've also defined an
+    <literal>AfterInvocationManager</literal>, although this is entirely
+    optional. The <literal>MethodSecurityInterceptor</literal> is also
+    configured with configuration attributes that apply to different
+    method signatures. A full discussion of configuration attributes is
+    provided in the High Level Design section of this document.</para>
+
+    <para>The <literal>MethodSecurityInterceptor</literal> can be
+    configured with configuration attributes in three ways. The first is
+    via a property editor and the application context, which is shown
+    above. The second is via defining the configuration attributes in your
+    source code using Jakarta Commons Attributes or Java 5 Annotations.
+    The third is via writing your own
+    <literal>ObjectDefinitionSource</literal>, although this is beyond the
+    scope of this document. Irrespective of the approach used, the
+    <literal>ObjectDefinitionSource</literal> is responsible for returning
+    a <literal>ConfigAttributeDefinition</literal> object that contains
+    all of the configuration attributes associated with a single secure
+    method.</para>
+
+    <para>It should be noted that the
+    <literal>MethodSecurityInterceptor.setObjectDefinitionSource()</literal>
+    method actually expects an instance of
+    <literal>MethodDefinitionSource</literal>. This is a marker interface
+    which subclasses <literal>ObjectDefinitionSource</literal>. It simply
+    denotes the <literal>ObjectDefinitionSource</literal> understands
+    <literal>MethodInvocation</literal>s. In the interests of simplicity
+    we'll continue to refer to the
+    <literal>MethodDefinitionSource</literal> as an
+    <literal>ObjectDefinitionSource</literal>, as the distinction is of
+    little relevance to most users of the
+    <literal>MethodSecurityInterceptor</literal>.</para>
+
+    <para>If using the application context property editor approach (as
+    shown above), commas are used to delimit the different configuration
+    attributes that apply to a given method pattern. Each configuration
+    attribute is assigned into its own <literal>SecurityConfig</literal>
+    object. The <literal>SecurityConfig</literal> object is discussed in
+    the High Level Design section.</para>
+
+    <para>If you are using the Jakarta Commons Attributes approach, your
+    bean context will be configured differently:</para>
+
+    <programlisting>&lt;bean id="attributes" class="org.springframework.metadata.commons.CommonsAttributes"/&gt;
+&lt;bean id="objectDefinitionSource"
+        class="org.springframework.security.intercept.method.MethodDefinitionAttributes"&gt;
+&lt;property name="attributes"&gt;&lt;ref local="attributes"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="bankManagerSecurity"
+        class="org.springframework.security.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
+&lt;property name="validateConfigAttributes"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+&lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
+&lt;property name="objectDefinitionSource"&gt;&lt;ref bean="objectDefinitionSource"/&gt;&lt;/property&gt;
+&lt;/bean&gt;       </programlisting>
+
+    <para>In addition, your source code will contain Jakarta Commons
+    Attributes tags that refer to a concrete implementation of
+    <literal>ConfigAttribute</literal>. The following example uses the
+    <literal>SecurityConfig</literal> implementation to represent the
+    configuration attributes, and results in the same security
+    configuration as provided by the property editor approach
+    above:</para>
+
+    <programlisting>public interface BankManager {
+
+/**
+ * @@SecurityConfig("ROLE_SUPERVISOR")
+ * @@SecurityConfig("RUN_AS_SERVER")
+ */
+public void deleteSomething(int id);
+
+/**
+ * @@SecurityConfig("ROLE_SUPERVISOR")
+ * @@SecurityConfig("RUN_AS_SERVER")
+ */
+public void deleteAnother(int id);
+
+/**
+ * @@SecurityConfig("ROLE_TELLER")
+ * @@SecurityConfig("ROLE_SUPERVISOR")
+ * @@SecurityConfig("BANKSECURITY_CUSTOMER")
+ * @@SecurityConfig("RUN_AS_SERVER")
+ */
+public float getBalance(int id);
+}</programlisting>
+
+    <para>If you are using the Spring Security Java 5 Annotations
+    approach, your bean context will be configured as follows:</para>
+
+    <programlisting>&lt;bean id="attributes"
+        class="org.springframework.security.annotation.SecurityAnnotationAttributes"/&gt;
+&lt;bean id="objectDefinitionSource"
+        class="org.springframework.security.intercept.method.MethodDefinitionAttributes"&gt;
+&lt;property name="attributes"&gt;&lt;ref local="attributes"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="bankManagerSecurity"
+        class="org.springframework.security.intercept.method.aopalliance.MethodSecurityInterceptor"&gt;
+&lt;property name="validateConfigAttributes"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+&lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
+&lt;property name="objectDefinitionSource"&gt;&lt;ref bean="objectDefinitionSource"/&gt;&lt;/property&gt;
+&lt;/bean&gt;        </programlisting>
+
+    <para>In addition, your source code will contain Spring Security Java
+    5 Security Annotations that represent the
+    <literal>ConfigAttribute</literal>. The following example uses the
+    <literal>@Secured</literal> annotations to represent the configuration
+    attributes, and results in the same security configuration as provided
+    by the property editor approach:</para>
+
+    <programlisting>import org.springframework.security.annotation.Secured;
+
+        public interface BankManager {
+
+/**
+ * Delete something
+ */
+@Secured({"ROLE_SUPERVISOR","RUN_AS_SERVER" })
+public void deleteSomething(int id);
+
+/**
+ * Delete another
+ */
+@Secured({"ROLE_SUPERVISOR","RUN_AS_SERVER" })
+public void deleteAnother(int id);
+
+/**
+ * Get balance
+ */
+@Secured({"ROLE_TELLER","ROLE_SUPERVISOR","BANKSECURITY_CUSTOMER","RUN_AS_SERVER" })
+public float getBalance(int id);
+}</programlisting>
+
+    <para>You might have noticed the
+    <literal>validateConfigAttributes</literal> property in the above
+    <literal>MethodSecurityInterceptor</literal> examples. When set to
+    <literal>true</literal> (the default), at startup time the
+    <literal>MethodSecurityInterceptor</literal> will evaluate if the
+    provided configuration attributes are valid. It does this by checking
+    each configuration attribute can be processed by either the
+    <literal>AccessDecisionManager</literal> or the
+    <literal>RunAsManager</literal>. If neither of these can process a
+    given configuration attribute, an exception is thrown. If using the
+    Jakarta Commons Attributes method of configuration, you should set
+    <literal>validateConfigAttributes</literal> to
+    <literal>false</literal>.</para>
+
+    <para>Please note that when using
+    <literal>BeanNameAutoProxyCreator</literal> to create the required
+    proxy for security, the configuration must contain the property
+    <literal>proxyTargetClass</literal> set to <literal>true</literal>.
+    Otherwise, the method passed to
+    <literal>MethodSecurityInterceptor.invoke</literal> is the proxy's
+    caller, not the proxy's target. Note that this introduces a
+    requirement on CGLIB. See an example of using
+    <literal>BeanNameAutoProxyCreator</literal> below:</para>
+
+    <programlisting>&lt;bean id="autoProxyCreator" class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator"&gt;
+&lt;property name="interceptorNames"&gt;
+&lt;list&gt;&lt;value&gt;methodSecurityInterceptor&lt;/value&gt;&lt;/list&gt;
+&lt;/property&gt;
+&lt;property name="beanNames"&gt;
+&lt;list&gt;&lt;value&gt;targetObjectName&lt;/value&gt;&lt;/list&gt;
+&lt;/property&gt;
+&lt;property name="proxyTargetClass" value="true"/&gt;
+&lt;/bean&gt;        </programlisting>
+  </sect1>
+
+  <sect1 id="aspectj">
+    <title>AspectJ (JoinPoint) Security Interceptor</title>
+
+    <para>The AspectJ security interceptor is very similar to the AOP
+    Alliance security interceptor discussed in the previous section.
+    Indeed we will only discuss the differences in this section.</para>
+
+    <para>The AspectJ interceptor is named
+    <literal>AspectJSecurityInterceptor</literal>. Unlike the AOP Alliance
+    security interceptor, which relies on the Spring application context
+    to weave in the security interceptor via proxying, the
+    <literal>AspectJSecurityInterceptor</literal> is weaved in via the
+    AspectJ compiler. It would not be uncommon to use both types of
+    security interceptors in the same application, with
+    <literal>AspectJSecurityInterceptor</literal> being used for domain
+    object instance security and the AOP Alliance
+    <literal>MethodSecurityInterceptor</literal> being used for services
+    layer security.</para>
+
+    <para>Let's first consider how the
+    <literal>AspectJSecurityInterceptor</literal> is configured in the
+    Spring application context:</para>
+
+    <programlisting>&lt;bean id="bankManagerSecurity"
+        class="org.springframework.security.intercept.method.aspectj.AspectJSecurityInterceptor"&gt;
+&lt;property name="validateConfigAttributes"&gt;&lt;value&gt;true&lt;/value&gt;&lt;/property&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+&lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
+&lt;property name="afterInvocationManager"&gt;&lt;ref bean="afterInvocationManager"/&gt;&lt;/property&gt;
+&lt;property name="objectDefinitionSource"&gt;
+&lt;value&gt;
+        org.springframework.security.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
+        org.springframework.security.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
+        &lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting>
+
+    <para>As you can see, aside from the class name, the
+    <literal>AspectJSecurityInterceptor</literal> is exactly the same as
+    the AOP Alliance security interceptor. Indeed the two interceptors can
+    share the same <literal>objectDefinitionSource</literal>, as the
+    <literal>ObjectDefinitionSource</literal> works with
+    <literal>java.lang.reflect.Method</literal>s rather than an AOP
+    library-specific class. Of course, your access decisions have access
+    to the relevant AOP library-specific invocation (ie
+    <literal>MethodInvocation</literal> or <literal>JoinPoint</literal>)
+    and as such can consider a range of addition criteria when making
+    access decisions (such as method arguments).</para>
+
+    <para>Next you'll need to define an AspectJ <literal>aspect</literal>.
+    For example:</para>
+
+    <programlisting>package org.springframework.security.samples.aspectj;
+
+        import org.springframework.security.intercept.method.aspectj.AspectJSecurityInterceptor;
+        import org.springframework.security.intercept.method.aspectj.AspectJCallback;
+        import org.springframework.beans.factory.InitializingBean;
+
+public aspect DomainObjectInstanceSecurityAspect implements InitializingBean {
+
+private AspectJSecurityInterceptor securityInterceptor;
+
+pointcut domainObjectInstanceExecution(): target(PersistableEntity)
+         &amp;&amp; execution(public * *(..)) &amp;&amp; !within(DomainObjectInstanceSecurityAspect);
+
+Object around(): domainObjectInstanceExecution() {
+if (this.securityInterceptor != null) {
+  AspectJCallback callback = new AspectJCallback() {
+    public Object proceedWithObject() {
+    return proceed();
+  }
+};
+return this.securityInterceptor.invoke(thisJoinPoint, callback);
+} else {
+  return proceed();
+}
+}
+
+public AspectJSecurityInterceptor getSecurityInterceptor() {
+return securityInterceptor;
+}
+
+public void setSecurityInterceptor(AspectJSecurityInterceptor securityInterceptor) {
+this.securityInterceptor = securityInterceptor;
+}
+
+public void afterPropertiesSet() throws Exception {
+if (this.securityInterceptor == null)
+  throw new IllegalArgumentException("securityInterceptor required");
+}
+}</programlisting>
+
+    <para>In the above example, the security interceptor will be applied
+    to every instance of <literal>PersistableEntity</literal>, which is an
+    abstract class not shown (you can use any other class or
+    <literal>pointcut</literal> expression you like). For those curious,
+    <literal>AspectJCallback</literal> is needed because the
+    <literal>proceed();</literal> statement has special meaning only
+    within an <literal>around()</literal> body. The
+    <literal>AspectJSecurityInterceptor</literal> calls this anonymous
+    <literal>AspectJCallback</literal> class when it wants the target
+    object to continue.</para>
+
+    <para>You will need to configure Spring to load the aspect and wire it
+    with the <literal>AspectJSecurityInterceptor</literal>. A bean
+    declaration which achieves this is shown below:</para>
+
+    <programlisting>
+&lt;bean id="domainObjectInstanceSecurityAspect"
+        class="org.springframework.security.samples.aspectj.DomainObjectInstanceSecurityAspect"
+        factory-method="aspectOf"&gt;
+&lt;property name="securityInterceptor"&gt;&lt;ref bean="aspectJSecurityInterceptor"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+    </programlisting>
+
+    <para>That's it! Now you can create your beans from anywhere within
+    your application, using whatever means you think fit (eg <literal>new
+    Person();</literal>) and they will have the security interceptor
+    applied.</para>
+  </sect1>
+
+  <sect1 id="filter-invocation-authorization">
+    <title>FilterInvocation Security Interceptor</title>
+
+    <para>To secure <literal>FilterInvocation</literal>s, developers need
+    to add a filter to their <literal>web.xml</literal> that delegates to
+    the <literal>FilterSecurityInterceptor</literal>. A typical
+    configuration example is provided below:</para>
+
+    <programlisting>&lt;filter&gt;
+&lt;filter-name&gt;Spring Security HTTP Request Security Filter&lt;/filter-name&gt;
+&lt;filter-class&gt;org.springframework.security.util.FilterToBeanProxy&lt;/filter-class&gt;
+&lt;init-param&gt;
+&lt;param-name&gt;targetClass&lt;/param-name&gt;
+&lt;param-value&gt;org.springframework.security.intercept.web.FilterSecurityInterceptor&lt;/param-value&gt;
+&lt;/init-param&gt;
+&lt;/filter&gt;
+
+&lt;filter-mapping&gt;
+&lt;filter-name&gt;Spring Security HTTP Request Security Filter&lt;/filter-name&gt;
+&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+&lt;/filter-mapping&gt;</programlisting>
+
+    <para>Notice that the filter is actually a
+    <literal>FilterToBeanProxy</literal>. Most of the filters used by
+    Spring Security use this class. Refer to the Filters section to learn
+    more about this bean.</para>
+
+    <para>In the application context you will need to configure three
+    beans:</para>
+
+    <programlisting>&lt;bean id="exceptionTranslationFilter"
+        class="org.springframework.security.ui.ExceptionTranslationFilter"&gt;
+&lt;property name="authenticationEntryPoint"&gt;&lt;ref local="authenticationEntryPoint"/&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="authenticationEntryPoint"
+        class="org.springframework.security.ui.webapp.AuthenticationProcessingFilterEntryPoint"&gt;
+&lt;property name="loginFormUrl"&gt;&lt;value&gt;/acegilogin.jsp&lt;/value&gt;&lt;/property&gt;
+&lt;property name="forceHttps"&gt;&lt;value&gt;false&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;
+
+&lt;bean id="filterSecurityInterceptor"
+        class="org.springframework.security.intercept.web.FilterSecurityInterceptor"&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+&lt;property name="objectDefinitionSource"&gt;
+&lt;value&gt;
+  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+  \A/secure/super/.*\Z=ROLE_WE_DONT_HAVE
+  \A/secure/.*\Z=ROLE_SUPERVISOR,ROLE_TELLER
+&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting>
+
+    <para>The <classname>ExceptionTranslationFilter</classname> provides
+    the bridge between Java exceptions and HTTP responses. It is solely
+    concerned with maintaining the user interface. This filter does not do
+    any actual security enforcement. If an
+    <exceptionname>AuthenticationException</exceptionname> is detected,
+    the filter will call the AuthenticationEntryPoint to commence the
+    authentication process (e.g. a user login).</para>
+
+    <para>The <literal>AuthenticationEntryPoint</literal> will be called
+    if the user requests a secure HTTP resource but they are not
+    authenticated. The class handles presenting the appropriate response
+    to the user so that authentication can begin. Three concrete
+    implementations are provided with Spring Security:
+    <literal>AuthenticationProcessingFilterEntryPoint</literal> for
+    commencing a form-based authentication,
+    <literal>BasicProcessingFilterEntryPoint</literal> for commencing a
+    HTTP Basic authentication process, and
+    <literal>CasProcessingFilterEntryPoint</literal> for commencing a
+    JA-SIG Central Authentication Service (CAS) login. The
+    <literal>AuthenticationProcessingFilterEntryPoint</literal> and
+    <literal>CasProcessingFilterEntryPoint</literal> have optional
+    properties related to forcing the use of HTTPS, so please refer to the
+    JavaDocs if you require this.</para>
+
+    <para><literal>FilterSecurityInterceptor</literal> is responsible for
+    handling the security of HTTP resources. Like any other security
+    interceptor, it requires a reference to an
+    <literal>AuthenticationManager</literal> and an
+    <literal>AccessDecisionManager</literal>, which are both discussed in
+    separate sections below. The
+    <literal>FilterSecurityInterceptor</literal> is also configured with
+    configuration attributes that apply to different HTTP URL requests. A
+    full discussion of configuration attributes is provided in the High
+    Level Design section of this document.</para>
+
+    <para>The <literal>FilterSecurityInterceptor</literal> can be
+    configured with configuration attributes in two ways. The first is via
+    a property editor and the application context, which is shown above.
+    The second is via writing your own
+    <literal>ObjectDefinitionSource</literal>, although this is beyond the
+    scope of this document. Irrespective of the approach used, the
+    <literal>ObjectDefinitionSource</literal> is responsible for returning
+    a <literal>ConfigAttributeDefinition</literal> object that contains
+    all of the configuration attributes associated with a single secure
+    HTTP URL.</para>
+
+    <para>It should be noted that the
+    <literal>FilterSecurityInterceptor.setObjectDefinitionSource()</literal>
+    method actually expects an instance of
+    <literal>FilterInvocationDefinitionSource</literal>. This is a marker
+    interface which subclasses <literal>ObjectDefinitionSource</literal>.
+    It simply denotes the <literal>ObjectDefinitionSource</literal>
+    understands <literal>FilterInvocation</literal>s. In the interests of
+    simplicity we'll continue to refer to the
+    <literal>FilterInvocationDefinitionSource</literal> as an
+    <literal>ObjectDefinitionSource</literal>, as the distinction is of
+    little relevance to most users of the
+    <literal>FilterSecurityInterceptor</literal>.</para>
+
+    <para>If using the application context property editor approach (as
+    shown above), commas are used to delimit the different configuration
+    attributes that apply to each HTTP URL. Each configuration attribute
+    is assigned into its own <literal>SecurityConfig</literal> object. The
+    <literal>SecurityConfig</literal> object is discussed in the High
+    Level Design section. The <literal>ObjectDefinitionSource</literal>
+    created by the property editor,
+    <literal>FilterInvocationDefinitionSource</literal>, matches
+    configuration attributes against <literal>FilterInvocations</literal>
+    based on expression evaluation of the request URL. Two standard
+    expression syntaxes are supported. The default is to treat all
+    expressions as regular expressions. Alternatively, the presence of a
+    <literal>PATTERN_TYPE_APACHE_ANT</literal> directive will cause all
+    expressions to be treated as Apache Ant paths. It is not possible to
+    mix expression syntaxes within the same definition. For example, the
+    earlier configuration could be generated using Apache Ant paths as
+    follows:</para>
+
+    <programlisting>&lt;bean id="filterInvocationInterceptor"
+        class="org.springframework.security.intercept.web.FilterSecurityInterceptor"&gt;
+&lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+&lt;property name="accessDecisionManager"&gt;&lt;ref bean="accessDecisionManager"/&gt;&lt;/property&gt;
+&lt;property name="runAsManager"&gt;&lt;ref bean="runAsManager"/&gt;&lt;/property&gt;
+&lt;property name="objectDefinitionSource"&gt;
+&lt;value&gt;
+  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+  PATTERN_TYPE_APACHE_ANT
+  /secure/super/**=ROLE_WE_DONT_HAVE
+  /secure/**=ROLE_SUPERVISOR,ROLE_TELLER
+&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting>
+
+    <para>Irrespective of the type of expression syntax used, expressions
+    are always evaluated in the order they are defined. Thus it is
+    important that more specific expressions are defined higher in the
+    list than less specific expressions. This is reflected in our example
+    above, where the more specific <literal>/secure/super/</literal>
+    pattern appears higher than the less specific
+    <literal>/secure/</literal> pattern. If they were reversed, the
+    <literal>/secure/</literal> pattern would always match and the
+    <literal>/secure/super/</literal> pattern would never be
+    evaluated.</para>
+
+    <para>The special keyword
+    <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> causes
+    the <literal>FilterInvocationDefinitionSource</literal> to
+    automatically convert a request URL to lowercase before comparison
+    against the expressions. Whilst by default the case of the request URL
+    is not converted, it is generally recommended to use
+    <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> and
+    write each expression assuming lowercase.</para>
+
+    <para>As with other security interceptors, the
+    <literal>validateConfigAttributes</literal> property is observed. When
+    set to <literal>true</literal> (the default), at startup time the
+    <literal>FilterSecurityInterceptor</literal> will evaluate if the
+    provided configuration attributes are valid. It does this by checking
+    each configuration attribute can be processed by either the
+    <literal>AccessDecisionManager</literal> or the
+    <literal>RunAsManager</literal>. If neither of these can process a
+    given configuration attribute, an exception is thrown.</para>
+  </sect1>
+</chapter>

src/docbkx/siteminder-auth-provider.xml

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="siteminder">
+<title>Siteminder Authentication Mechanism</title>
+
+<sect1 id="siteminder-overview">
+    <title>Overview</title>
+    
+    <para>Siteminder is a commercial single sign on solution by Computer
+        Associates.</para>
+    
+    <para>Spring Security provides a filter,
+        <literal>SiteminderAuthenticationProcessingFilter</literal> and
+        provider, <literal>SiteminderAuthenticationProvider</literal> that can
+        be used to process requests that have been pre-authenticated by
+        Siteminder. This filter assumes that you're using Siteminder for
+        <emphasis>authentication</emphasis>, and that you're using Spring
+        Security for <emphasis>authorization</emphasis>. The use of Siteminder
+        for <emphasis>authorization</emphasis> is not yet directly supported
+        by Spring Security.</para>
+    
+    <para>When using Siteminder, an agent is setup on your web server to
+        intercept a principal's first call to your application. The agent
+        redirects the web request to a single sign-on login page, and once
+        authenticated, your application receives the request. Inside the HTTP
+        request is a header - such as <literal>SM_USER</literal> - which
+        identifies the authenticated principal (please refer to your
+        organization's "single sign-on" group for header details in your
+        particular configuration).</para>
+</sect1>
+
+<sect1 id="siteminder-config">
+    <title>Configuration</title>
+    
+    <para>The first step in setting up Spring Security's Siteminder
+        support is to define the authentication mechanism that will inspect
+        the HTTP header discussed earlier. It will be responsible for
+        generating a <literal>UsernamePasswordAuthenticationToken</literal>
+        that is later sent to the
+        <literal>SiteminderAuthenticationProvider</literal>. Let's look at an
+        example:</para>
+    
+    <para><programlisting>&lt;bean id="authenticationProcessingFilter"
+        class="org.springframework.security.ui.webapp.SiteminderAuthenticationProcessingFilter"&gt;
+        &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
+        &lt;property name="authenticationFailureUrl"&gt;&lt;value&gt;/login.jsp?login_error=1&lt;/value&gt;&lt;/property&gt;
+        &lt;property name="defaultTargetUrl"&gt;&lt;value&gt;/security.do?method=getMainMenu&lt;/value&gt;&lt;/property&gt;
+        &lt;property name="filterProcessesUrl"&gt;&lt;value&gt;/j_spring_security_check&lt;/value&gt;&lt;/property&gt;
+        &lt;property name="siteminderUsernameHeaderKey"&gt;&lt;value&gt;SM_USER&lt;/value&gt;&lt;/property&gt;
+        &lt;property name="formUsernameParameterKey"&gt;&lt;value&gt;j_username&lt;/value&gt;&lt;/property&gt;
+        &lt;/bean&gt;</programlisting></para>
+    
+    <para>In our example above, the bean is being provided an
+        <literal>AuthenticationManager</literal>, as is normally needed by
+        authentication mechanisms. Several URLs are also specified, with the
+        values being self-explanatory. It's important to also specify the HTTP
+        header that Spring Security should inspect. If you additionally want
+        to support form-based authentication (i.e. in your development
+        environment where Siteminder is not installed), specify the form's
+        username parameter as well - just don't do this in production!</para>
+    
+    <para>Note that you'll need a
+        <literal><literal>SiteminderAuthenticationProvider</literal></literal>
+        configured against your <literal>ProviderManager</literal> in order to
+        use the Siteminder authentication mechanism. Normally an
+        <literal>AuthenticationProvider</literal> expects the password
+        property to match what it retrieves from the
+        <literal>UserDetailsSource</literal>, but in this case, authentication
+        has already been handled by Siteminder, so password property is not
+        even relevant. This may sound like a security weakness, but remember
+        that users have to authenticate with Siteminder before your
+        application ever receives the requests, so the purpose of your custom
+        <literal>UserDetailsService</literal> should simply be to build the
+        complete <literal>Authentication</literal> object (ie with suitable
+        <literal>GrantedAuthority[]</literal>s).</para>
+    
+    <para>Advanced tip and word to the wise: If you additionally want to
+        support form-based authentication in your development environment
+        (where Siteminder is typically not installed), specify the form's
+        username parameter as well. Just don't do this in production!</para>
+</sect1>
+</chapter>

src/docbkx/supporting-infrastructure.xml

@@ -0,0 +1,332 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="supporting-infrastructure">
+  <title>Supporting Infrastructure</title>
+
+  <para>This chapter introduces some of the supplementary and supporting
+  infrastructure used by Spring Security. If a capability is not directly
+  related to security, yet included in the Spring Security project, we
+  will discuss it in this chapter.</para>
+
+  <sect1 id="localization">
+    <title>Localization</title>
+
+    <para>Spring Security supports localization of exception messages that
+    end users are likely to see. If your application is designed for
+    English users, you don't need to do anything as by default all
+    Security Security messages are in English. If you need to support
+    other locales, everything you need to know is contained in this
+    section.</para>
+
+    <para>All exception messages can be localized, including messages
+    related to authentication failures and access being denied
+    (authorization failures). Exceptions and logging that is focused on
+    developers or system deployers (including incorrect attributes,
+    interface contract violations, using incorrect constructors, startup
+    time validation, debug-level logging) etc are not localized and
+    instead are hard-coded in English within Spring Security's
+    code.</para>
+
+    <para>Shipping in the <literal>acegi-security-xx.jar</literal> you
+    will find an <literal>org.springframework.security</literal> package
+    that in turn contains a <literal>messages.properties</literal> file.
+    This should be referred to by your
+    <literal>ApplicationContext</literal>, as Acegi Security classes
+    implement Spring's <literal>MessageSourceAware</literal> interface and
+    expect the message resolver to be dependency injected at application
+    context startup time. Usually all you need to do is register a bean
+    inside your application context to refer to the messages. An example
+    is shown below:</para>
+
+    <para><programlisting>&lt;bean id="messageSource" class="org.springframework.context.support.ReloadableResourceBundleMessageSource"&gt;
+&lt;property name="basename"&gt;&lt;value&gt;org/acegisecurity/messages&lt;/value&gt;&lt;/property&gt;
+&lt;/bean&gt;        </programlisting></para>
+
+    <para>The <literal>messages.properties</literal> is named in
+    accordance with standard resource bundles and represents the default
+    language supported by Spring Security messages. This default file is
+    in English. If you do not register a message source, Spring Security
+    will still work correctly and fallback to hard-coded English versions
+    of the messages.</para>
+
+    <para>If you wish to customize the
+    <literal>messages.properties</literal> file, or support other
+    languages, you should copy the file, rename it accordingly, and
+    register it inside the above bean definition. There are not a large
+    number of message keys inside this file, so localization should not be
+    considered a major initiative. If you do perform localization of this
+    file, please consider sharing your work with the community by logging
+    a JIRA task and attaching your appropriately-named localized version
+    of <literal>messages.properties</literal>.</para>
+
+    <para>Rounding out the discussion on localization is the Spring
+    <literal>ThreadLocal</literal> known as
+    <literal>org.springframework.context.i18n.LocaleContextHolder</literal>.
+    You should set the <literal>LocaleContextHolder</literal> to represent
+    the preferred <literal>Locale</literal> of each user. Spring Security
+    will attempt to locate a message from the message source using the
+    <literal>Locale</literal> obtained from this
+    <literal>ThreadLocal</literal>. Please refer to Spring documentation
+    for further details on using <literal>LocaleContextHolder</literal>
+    and the helper classes that can automatically set it for you (eg
+    <literal>AcceptHeaderLocaleResolver</literal>,
+    <literal>CookieLocaleResolver</literal>,
+    <literal>FixedLocaleResolver</literal>,
+    <literal>SessionLocaleResolver</literal> etc)</para>
+  </sect1>
+
+  <sect1 id="filters">
+    <title>Filters</title>
+
+    <para>Spring Security uses many filters, as referred to throughout the
+    remainder of this reference guide. You have a choice in how these
+    filters are added to your web application, in that you can use either
+    <literal>FilterToBeanProxy</literal> or
+    <literal>FilterChainProxy</literal>. We'll look at both below.</para>
+
+    <para>Most filters are configured using the
+    <literal>FilterToBeanProxy</literal>. An example configuration from
+    <literal>web.xml</literal> follows:</para>
+
+    <para><programlisting>&lt;filter&gt;
+&lt;filter-name&gt;Spring Security HTTP Request Security Filter&lt;/filter-name&gt;
+&lt;filter-class&gt;org.springframework.security.util.FilterToBeanProxy&lt;/filter-class&gt;
+&lt;init-param&gt;
+&lt;param-name&gt;targetClass&lt;/param-name&gt;
+&lt;param-value&gt;org.springframework.security.ClassThatImplementsFilter&lt;/param-value&gt;
+&lt;/init-param&gt;
+&lt;/filter&gt;</programlisting></para>
+
+    <para>Notice that the filter in <literal>web.xml</literal> is actually
+    a <literal>FilterToBeanProxy</literal>, and not the filter that will
+    actually implement the logic of the filter. What
+    <literal>FilterToBeanProxy</literal> does is delegate the
+    <literal>Filter</literal>'s methods through to a bean which is
+    obtained from the Spring application context. This enables the bean to
+    benefit from the Spring application context lifecycle support and
+    configuration flexibility. The bean must implement
+    <literal>javax.servlet.Filter</literal>.</para>
+
+    <para>The <literal>FilterToBeanProxy</literal> only requires a single
+    initialization parameter, <literal>targetClass</literal> or
+    <literal>targetBean</literal>. The <literal>targetClass</literal>
+    parameter locates the first object in the application context of the
+    specified class, whilst <literal>targetBean</literal> locates the
+    object by bean name. Like standard Spring web applications, the
+    <literal>FilterToBeanProxy</literal> accesses the application context
+    via<literal>
+    WebApplicationContextUtils.getWebApplicationContext(ServletContext)</literal>,
+    so you should configure a <literal>ContextLoaderListener</literal> in
+    <literal>web.xml</literal>.</para>
+
+    <para>There is a lifecycle issue to consider when hosting
+    <literal>Filter</literal>s in an IoC container instead of a servlet
+    container. Specifically, which container should be responsible for
+    calling the <literal>Filter</literal>'s "startup" and "shutdown"
+    methods? It is noted that the order of initialization and destruction
+    of a <literal>Filter</literal> can vary by servlet container, and this
+    can cause problems if one <literal>Filter</literal> depends on
+    configuration settings established by an earlier initialized
+    <literal>Filter</literal>. The Spring IoC container on the other hand
+    has more comprehensive lifecycle/IoC interfaces (such as
+    <literal>InitializingBean</literal>,
+    <literal>DisposableBean</literal>, <literal>BeanNameAware</literal>,
+    <literal>ApplicationContextAware</literal> and many others) as well as
+    a well-understood interface contract, predictable method invocation
+    ordering, autowiring support, and even options to avoid implementing
+    Spring interfaces (eg the <literal>destroy-method</literal> attribute
+    in Spring XML). For this reason we recommend the use of Spring
+    lifecycle services instead of servlet container lifecycle services
+    wherever possible. By default <literal>FilterToBeanProxy</literal>
+    will not delegate <literal>init(FilterConfig)</literal> and
+    <literal>destroy()</literal> methods through to the proxied bean. If
+    you do require such invocations to be delegated, set the
+    <literal>lifecycle</literal> initialization parameter to
+    <literal>servlet-container-managed</literal>.</para>
+
+    <para>Rather than using <literal>FilterToBeanProxy</literal>, we
+    strongly recommend to use <literal>FilterChainProxy</literal> instead.
+    Whilst <literal>FilterToBeanProxy</literal> is a very useful class,
+    the problem is that the lines of code required for
+    <literal>&lt;filter&gt;</literal> and
+    <literal>&lt;filter-mapping&gt;</literal> entries in
+    <literal>web.xml</literal> explodes when using more than a few
+    filters. To overcome this issue, Spring Security provides a
+    <literal>FilterChainProxy</literal> class. It is wired using a
+    <literal>FilterToBeanProxy</literal> (just like in the example above),
+    but the target class is
+    <literal>org.springframework.security.util.FilterChainProxy</literal>.
+    The filter chain is then declared in the application context, using
+    code such as this:</para>
+
+    <para><programlisting>&lt;bean id="filterChainProxy"
+        class="org.springframework.security.util.FilterChainProxy"&gt;
+&lt;property name="filterInvocationDefinitionSource"&gt;
+&lt;value&gt;
+  CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
+  PATTERN_TYPE_APACHE_ANT
+  /webServices/**=httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor
+  /**=httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor
+&lt;/value&gt;
+&lt;/property&gt;
+&lt;/bean&gt;        </programlisting></para>
+
+    <para>You may notice similarities with the way
+    <literal>FilterSecurityInterceptor</literal> is declared. Both regular
+    expressions and Ant Paths are supported, and the most specific URIs
+    appear first. At runtime the <literal>FilterChainProxy</literal> will
+    locate the first URI pattern that matches the current web request.
+    Each of the corresponding configuration attributes represent the name
+    of a bean defined in the application context. The filters will then be
+    invoked in the order they are specified, with standard
+    <literal>FilterChain</literal> behaviour being respected (a
+    <literal>Filter</literal> can elect not to proceed with the chain if
+    it wishes to end processing).</para>
+
+    <para>As you can see, <literal>FilterChainProxy</literal> requires the
+    duplication of filter names for different request patterns (in the
+    above example, <literal>exceptionTranslationFilter</literal> and
+    <literal>filterSecurityInterceptor</literal> are duplicated). This
+    design decision was made to enable <literal>FilterChainProxy</literal>
+    to specify different <literal>Filter</literal> invocation orders for
+    different URI patterns, and also to improve both the expressiveness
+    (in terms of regular expressions, Ant Paths, and any custom
+    <literal>FilterInvocationDefinitionSource</literal> implementations)
+    and clarity of which <literal>Filter</literal>s should be
+    invoked.</para>
+
+    <para>You may have noticed we have declared two
+    <literal>HttpSessionContextIntegrationFilter</literal>s in the filter
+    chain (<literal>ASC</literal> is short for
+    <literal>allowSessionCreation</literal>, a property of
+    <literal>HttpSessionContextIntegrationFilter</literal>). As web
+    services will never present a <literal>jsessionid</literal> on future
+    requests, creating <literal>HttpSession</literal>s for such user
+    agents would be wasteful. If you had a high-volume application which
+    required maximum scalability, we recommend you use the approach shown
+    above. For smaller applications, using a single
+    <literal>HttpSessionContextIntegrationFilter</literal> (with its
+    default <literal>allowSessionCreation</literal> as
+    <literal>true</literal>) would likely be sufficient.</para>
+
+    <para>In relation to lifecycle issues, the
+    <literal>FilterChainProxy</literal> will always delegate
+    <literal>init(FilterConfig)</literal> and <literal>destroy()</literal>
+    methods through to the underlaying <literal>Filter</literal>s if such
+    methods are called against <literal>FilterChainProxy</literal> itself.
+    In this case, <literal>FilterChainProxy</literal> guarantees to only
+    initialize and destroy each <literal>Filter</literal> once,
+    irrespective of how many times it is declared by the
+    <literal>FilterInvocationDefinitionSource</literal>. You control the
+    overall choice as to whether these methods are called or not via the
+    <literal>lifecycle</literal> initialization parameter of the
+    <literal>FilterToBeanProxy</literal> that proxies
+    <literal>FilterChainProxy</literal>. As discussed above, by default
+    any servlet container lifecycle invocations are not delegated through
+    to <literal>FilterChainProxy</literal>.</para>
+
+    <para>You can also omit a URI pattern from the filter chain by using
+    the token <literal>#NONE#</literal> on the right-hand side of the
+    <literal>&lt;URI Pattern&gt; = &lt;Filter Chain&gt;</literal>
+    expression. For example, using the example above, if you wanted to
+    exclude the <filename>/webservices</filename> location completely, you
+    would modify the corresponding line in the bean declaration to be
+    <programlisting>
+/webServices/**=#NONE#
+    </programlisting> Note that anything matching this path will then have
+    no authentication or authorization services applied and will be freely
+    accessible.</para>
+
+    <para>The order that filters are defined in <literal>web.xml</literal>
+    is very important. Irrespective of which filters you are actually
+    using, the order of the <literal>&lt;filter-mapping&gt;</literal>s
+    should be as follows:</para>
+
+    <orderedlist>
+      <listitem>
+        <para><literal>ChannelProcessingFilter</literal>, because it might
+        need to redirect to a different protocol</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>ConcurrentSessionFilter</literal>, because it
+        doesn't use any <literal>SecurityContextHolder</literal>
+        functionality but needs to update the
+        <literal>SessionRegistry</literal> to reflect ongoing requests
+        from the principal</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>HttpSessionContextIntegrationFilter</literal>, so a
+        <literal>SecurityContext</literal> can be setup in the
+        <literal>SecurityContextHolder</literal> at the beginning of a web
+        request, and any changes to the <literal>SecurityContext</literal>
+        can be copied to the <literal>HttpSession</literal> when the web
+        request ends (ready for use with the next web request)</para>
+      </listitem>
+
+      <listitem>
+        <para>Authentication processing mechanisms -
+        <literal>AuthenticationProcessingFilter</literal>,
+        <literal>CasProcessingFilter</literal>,
+        <literal>BasicProcessingFilter, HttpRequestIntegrationFilter,
+        JbossIntegrationFilter</literal> etc - so that the
+        <literal>SecurityContextHolder</literal> can be modified to
+        contain a valid <literal>Authentication</literal> request
+        token</para>
+      </listitem>
+
+      <listitem>
+        <para>The
+        <literal>SecurityContextHolderAwareRequestFilter</literal>, if you
+        are using it to install a Spring Security aware
+        <literal>HttpServletRequestWrapper</literal> into your servlet
+        container</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>RememberMeProcessingFilter</literal>, so that if no
+        earlier authentication processing mechanism updated the
+        <literal>SecurityContextHolder</literal>, and the request presents
+        a cookie that enables remember-me services to take place, a
+        suitable remembered
+        <literal><literal>Authentication</literal></literal> object will
+        be put there</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>AnonymousProcessingFilter</literal>, so that if no
+        earlier authentication processing mechanism updated the
+        <literal>SecurityContextHolder</literal>, an anonymous
+        <literal>Authentication</literal> object will be put there</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>ExceptionTranslationFilter</literal>, to catch any
+        Spring Security exceptions so that either an HTTP error response
+        can be returned or an appropriate
+        <literal>AuthenticationEntryPoint</literal> can be launched</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>FilterSecurityInterceptor</literal>, to protect web
+        URIs</para>
+      </listitem>
+    </orderedlist>
+
+    <para>All of the above filters use
+    <literal>FilterToBeanProxy</literal> or
+    <literal>FilterChainProxy</literal>. It is recommended that a single
+    <literal>FilterToBeanProxy</literal> proxy through to a single
+    <literal>FilterChainProxy</literal> for each application, with that
+    <literal>FilterChainProxy</literal> defining all of Spring Security
+    <literal>Filter</literal>s.</para>
+
+    <para>If you're using SiteMesh, ensure Spring Security filters execute
+    before the SiteMesh filters are called. This enables the
+    <literal>SecurityContextHolder</literal> to be populated in time for
+    use by SiteMesh decorators</para>
+  </sect1>
+</chapter>

src/docbkx/taglibs.xml

@@ -0,0 +1,44 @@
+<chapter id="taglib">    
+    <title>Tag Libraries</title>
+    
+    <sect1 id="taglib-overview">
+        <title>Overview</title>
+        
+        <para>Spring Security comes bundled with several JSP tag libraries
+            that eases JSP writing. The tag libraries provide a range of different
+            services.</para>
+    </sect1>
+    
+    <sect1 id="taglib-config">
+        <title>Configuration</title>
+        
+        <para>All taglib classes are included in the core
+            <literal>spring-security-xx.jar</literal> file, with the
+            <literal>security.tld</literal> located in the JAR's
+            <literal>META-INF</literal> directory. This means for JSP 1.2+ web
+            containers you can simply include the JAR in the WAR's
+            <literal>WEB-INF/lib</literal> directory and it will be available. If
+            you're using a JSP 1.1 container, you'll need to declare the JSP
+            taglib in your <literal>web.xml file</literal>, and include
+            <literal>security.tld</literal> in the <literal>WEB-INF/lib</literal>
+            directory. The following fragment is added to
+            <literal>web.xml</literal>:</para>
+        
+        <para><programlisting>&lt;taglib&gt;
+            &lt;taglib-uri&gt;http://www.springframework.org/security/tags&lt;/taglib-uri&gt;
+            &lt;taglib-location&gt;/WEB-INF/security.tld&lt;/taglib-location&gt;
+            &lt;/taglib&gt;       </programlisting></para>
+    </sect1>
+    
+    <sect1 id="taglib-usage">
+        <title>Usage</title>
+        
+        <para>Now that you've configured the tag libraries, refer to the
+            individual reference guide sections for details on how to use them.
+            Note that when using the tags, you should include the taglib reference
+            in your JSP: <programlisting>
+                &lt;%@ taglib prefix='security' uri='http://www.springframework.org/security/tags' %&gt;
+                
+            </programlisting></para>
+    </sect1>
+</chapter>

src/docbkx/technical-overview.xml

@@ -0,0 +1,522 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">    
+
+<chapter id="technical-overview">
+  <title>Technical Overview</title>
+
+  <sect1 id="runtime-environment">
+    <title>Runtime Environment</title>
+
+    <para>Spring Security is written to execute within a standard Java 1.4
+    Runtime Environment. It also supports Java 5.0, although the Java
+    types which are specific to this release are packaged in a separate
+    package with the suffix "tiger" in their JAR filename. As Spring
+    Security aims to operate in a self-contained manner, there is no need
+    to place any special configuration files into your Java Runtime
+    Environment. In particular, there is no need to configure a special
+    Java Authentication and Authorization Service (JAAS) policy file or
+    place Spring Security into common classpath locations.</para>
+
+    <para>Similarly, if you are using an EJB Container or Servlet
+    Container there is no need to put any special configuration files
+    anywhere, nor include Spring Security in a server classloader.</para>
+
+    <para>This above design offers maximum deployment time flexibility, as
+    you can simply copy your target artifact (be it a JAR, WAR or EAR)
+    from one system to another and it will immediately work.</para>
+  </sect1>
+
+  <sect1 id="shared-components">
+    <title>Shared Components</title>
+
+    <para>Let's explore some of the most important shared components in
+    Spring Security. Components are considered "shared" if they are
+    central to the framework and the framework cannot operate without
+    them. These Java types represent the building blocks of the remaining
+    system, so it's important to understand that they're there, even if
+    you don't need to directly interact with them.</para>
+
+    <para>The most fundamental object is
+    <literal>SecurityContextHolder</literal>. This is where we store
+    details of the present security context of the application, which
+    includes details of the principal currently using the application. By
+    default the <literal>SecurityContextHolder</literal> uses a
+    <literal>ThreadLocal</literal> to store these details, which means
+    that the security context is always available to methods in the same
+    thread of execution, even if the security context is not explicitly
+    passed around as an argument to those methods. Using a
+    <literal>ThreadLocal</literal> in this way is quite safe if care is
+    taken to clear the thread after the present principal's request is
+    processed. Of course, Spring Security takes care of this for you
+    automatically so there is no need to worry about it.</para>
+
+    <para>Some applications aren't entirely suitable for using a
+    <literal>ThreadLocal</literal>, because of the specific way they work
+    with threads. For example, a Swing client might want all threads in a
+    Java Virtual Machine to use the same security context. For this
+    situation you would use the
+    <literal>SecurityContextHolder.MODE_GLOBAL</literal>. Other
+    applications might want to have threads spawned by the secure thread
+    also assume the same security identity. This is achieved by using
+    <literal>SecurityContextHolder.MODE_INHERITABLETHREADLOCAL</literal>.
+    You can change the mode from the default
+    <literal>SecurityContextHolder.MODE_THREADLOCAL</literal> in two ways.
+    The first is to set a system property. Alternatively, call a static
+    method on <literal>SecurityContextHolder</literal>. Most applications
+    won't need to change from the default, but if you do, take a look at
+    the JavaDocs for <literal>SecurityContextHolder</literal> to learn
+    more.</para>
+
+    <para>Inside the <literal>SecurityContextHolder</literal> we store
+    details of the principal currently interacting with the application.
+    Spring Security uses an <literal>Authentication</literal> object to
+    represent this information. Whilst you won't normally need to create
+    an <literal>Authentication</literal> object yourself, it is fairly
+    common for users to query the <literal>Authentication</literal>
+    object. You can use the following code block - from anywhere in your
+    application - to do this:</para>
+
+    <programlisting>Object obj = SecurityContextHolder.getContext().getAuthentication().getPrincipal();
+
+if (obj instanceof UserDetails) {
+String username = ((UserDetails)obj).getUsername();
+} else {
+String username = obj.toString();
+}</programlisting>
+
+    <para>The above code introduces a number of interesting relationships
+    and key objects. First, you will notice that there is an intermediate
+    object between <literal>SecurityContextHolder</literal> and
+    <literal>Authentication</literal>. The
+    <literal>SecurityContextHolder.getContext()</literal> method is
+    actually returning a <literal>SecurityContext</literal>. Spring
+    Security uses a few different <literal>SecurityContext</literal>
+    implementations, such as if we need to store special information
+    related to a request that is not principal-specific. A good example of
+    this is our JCaptcha integration, which needs to know whether the
+    current request came from a human user or not. Because such a decision
+    has nothing at all to do with the principal the request may or may not
+    be authenticated as, we store it in the
+    <literal>SecurityContext</literal>.</para>
+
+    <para>Another item to note from the above code fragment is that you
+    can obtain a principal from the <literal>Authentication</literal>
+    object. The principal is just an <literal>Object</literal>. Most of
+    the time this can be cast into a <literal>UserDetails</literal>
+    object. <literal>UserDetails</literal> is a central interface in
+    Spring Security. It represents a principal, but in an extensible and
+    application-specific way. Think of <literal>UserDetails</literal> as
+    the adapter between your own user database and what Spring Security
+    needs inside the <literal>SecurityContextHolder</literal>. Being a
+    representation of something from your own user database, quite often
+    you will cast the <literal>UserDetails</literal> to the original
+    object that your application provided, so you can call
+    business-specific methods (like <literal>getEmail()</literal>,
+    <literal>getEmployeeNumber()</literal> and so on).</para>
+
+    <para>By now you're probably wondering, so when do I provide a
+    <literal>UserDetails</literal> object? How do I do that? I thought you
+    said this thing was declarative and I didn't need to write any Java
+    code - what gives? The short answer is that there is a special
+    interface called <literal>UserDetailsService</literal>. The only
+    method on this interface accepts a <literal>String</literal>-based
+    username argument and returns a <literal>UserDetails</literal>. Most
+    authentication providers that ship with Spring Security delegate to a
+    <literal>UserDetailsService</literal> as part of the authentication
+    process. The <literal>UserDetailsService</literal> is used to build
+    the <literal>Authentication</literal> object that is stored in the
+    <literal>SecurityContextHolder</literal>. The good news is that we
+    provide a number of <literal>UserDetailsService</literal>
+    implementations, including one that uses an in-memory map and another
+    that uses JDBC. Most users tend to write their own, though, with such
+    implementations often simply sitting on top of an existing Data Access
+    Object (DAO) that represents their employees, customers, or other
+    users of the enterprise application. Remember the advantage that
+    whatever your UserDetailsService returns can always be obtained from
+    the <literal>SecurityContextHolder</literal>, as per the above code
+    fragment.</para>
+
+    <para>Besides the principal, another important method provided by
+    <literal>Authentication</literal> is
+    <literal>getAuthorities(</literal>). This method provides an array of
+    <literal>GrantedAuthority</literal> objects. A
+    <literal>GrantedAuthority</literal> is, not surprisingly, an authority
+    that is granted to the principal. Such authorities are usually
+    "roles", such as <literal>ROLE_ADMINISTRATOR</literal> or
+    <literal>ROLE_HR_SUPERVISOR</literal>. These roles are later on
+    configured for web authorization, method authorization and domain
+    object authorization. Other parts of Spring Security are capable of
+    interpreting these authorities, and expect them to be present.
+    <literal>GrantedAuthority</literal> objects are usually loaded by the
+    <literal>UserDetailsService</literal>.</para>
+
+    <para>Usually the <literal>GrantedAuthority</literal> objects are
+    application-wide permissions. They are not specific to a given domain
+    object. Thus, you wouldn't likely have a
+    <literal>GrantedAuthority</literal> to represent a permission to
+    <literal>Employee</literal> object number 54, because if there are
+    thousands of such authorities you would quickly run out of memory (or,
+    at the very least, cause the application to take a long time to
+    authenticate a user). Of course, Spring Security is expressly designed
+    to handle this common requirement, but you'd instead use the project's
+    domain object security capabilities for this purpose.</para>
+
+    <para>Last but not least, sometimes you will need to store the
+    <literal>SecurityContext</literal> between HTTP requests. Other times
+    the principal will re-authenticate on every request, although most of
+    the time it will be stored. The
+    <literal>HttpSessionContextIntegrationFilter</literal> is responsible
+    for storing a <literal>SecurityContext</literal> between HTTP
+    requests. As suggested by the name of the class, the
+    <literal>HttpSession</literal> is used to store this information. You
+    should never interact directly with the <literal>HttpSession</literal>
+    for security purposes. There is simply no justification for doing so -
+    always use the <literal>SecurityContextHolder</literal>
+    instead.</para>
+
+    <para>Just to recap, the major building blocks of Spring Security
+    are:</para>
+
+    <itemizedlist spacing="compact">
+      <listitem>
+        <para><literal>SecurityContextHolder</literal>, to provide any
+        type access to the <literal>SecurityContext</literal>.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>SecurityContext</literal>, to hold the
+        <literal>Authentication</literal> and possibly request-specific
+        security information.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>HttpSessionContextIntegrationFilter</literal>, to
+        store the <literal>SecurityContext</literal> in the
+        <literal>HttpSession</literal> between web requests.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>Authentication</literal>, to represent the
+        principal in a Spring Security-specific manner.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>GrantedAuthority</literal>, to reflect the
+        application-wide permissions granted to a principal.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>UserDetails</literal>, to provide the necessary
+        information to build an Authentication object from your
+        application's DAOs.</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>UserDetailsService</literal>, to create a
+        <literal>UserDetails</literal> when passed in a
+        <literal>String</literal>-based username (or certificate ID or
+        alike).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Now that you've gained an understanding of these repeatedly-used
+    components, let's take a closer look at the process of
+    authentication.</para>
+  </sect1>
+
+  <sect1 id="common-authentication">
+    <title>Authentication</title>
+
+    <para>As mentioned in the beginning of this reference guide, Spring
+    Security can participate in many different authentication
+    environments. Whilst we recommend people use Spring Security for
+    authentication and not integrate with existing Container Managed
+    Authentication, it is nevertheless supported - as is integrating with
+    your own proprietary authentication system. Let's first explore
+    authentication from the perspective of Spring Security managing web
+    security entirely on its own, which is illustrative of the most
+    complex and most common situation.</para>
+
+    <para>Consider a typical web application's authentication
+    process:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>You visit the home page, and click on a link.</para>
+      </listitem>
+
+      <listitem>
+        <para>A request goes to the server, and the server decides that
+        you've asked for a protected resource.</para>
+      </listitem>
+
+      <listitem>
+        <para>As you're not presently authenticated, the server sends back
+        a response indicating that you must authenticate. The response
+        will either be an HTTP response code, or a redirect to a
+        particular web page.</para>
+      </listitem>
+
+      <listitem>
+        <para>Depending on the authentication mechanism, your browser will
+        either redirect to the specific web page so that you can fill out
+        the form, or the browser will somehow retrieve your identity (eg a
+        BASIC authentication dialogue box, a cookie, a X509 certificate
+        etc).</para>
+      </listitem>
+
+      <listitem>
+        <para>The browser will send back a response to the server. This
+        will either be an HTTP POST containing the contents of the form
+        that you filled out, or an HTTP header containing your
+        authentication details.</para>
+      </listitem>
+
+      <listitem>
+        <para>Next the server will decide whether or not the presented
+        credentials are valid. If they're valid, the next step will
+        happen. If they're invalid, usually your browser will be asked to
+        try again (so you return to step two above).</para>
+      </listitem>
+
+      <listitem>
+        <para>The original request that you made to cause the
+        authentication process will be retried. Hopefully you've
+        authenticated with sufficient granted authorities to access the
+        protected resource. If you have sufficient access, the request
+        will be successful. Otherwise, you'll receive back an HTTP error
+        code 403, which means "forbidden".</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Spring Security has distinct classes responsible for most of the
+    steps described above. The main participants (in the order that they
+    are used) are the <literal>ExceptionTranslationFilter</literal>, an
+    <literal>AuthenticationEntryPoint</literal>, an authentication
+    mechanism, and an <literal>AuthenticationProvider</literal>.</para>
+
+    <para><literal>ExceptionTranslationFilter</literal> is an Acegi
+    Security filter that has responsibility for detecting any Acegi
+    Security exceptions that are thrown. Such exceptions will generally be
+    thrown by an <literal>AbstractSecurityInterceptor</literal>, which is
+    the main provider of authorization services. We will discuss
+    <literal>AbstractSecurityInterceptor</literal> in the next section,
+    but for now we just need to know that it produces Java exceptions and
+    knows nothing about HTTP or how to go about authenticating a
+    principal. Instead the <literal>ExceptionTranslationFilter</literal>
+    offers this service, with specific responsibility for either returning
+    error code 403 (if the principal has been authenticated and therefore
+    simply lacks sufficient access - as per step seven above), or
+    launching an <literal>AuthenticationEntryPoint</literal> (if the
+    principal has not been authenticated and therefore we need to go
+    commence step three).</para>
+
+    <para>The <literal>AuthenticationEntryPoint</literal> is responsible
+    for step three in the above list. As you can imagine, each web
+    application will have a default authentication strategy (well, this
+    can be configured like nearly everything else in Spring Security, but
+    let's keep it simple for now). Each major authentication system will
+    have its own <literal>AuthenticationEntryPoint</literal>
+    implementation, which takes actions such as described in step
+    three.</para>
+
+    <para>After your browser decides to submit your authentication
+    credentials (either as an HTTP form post or HTTP header) there needs
+    to be something on the server that "collects" these authentication
+    details. By now we're at step six in the above list. In Spring
+    Security we have a special name for the function of collecting
+    authentication details from a user agent (usually a web browser), and
+    that name is "authentication mechanism". After the authentication
+    details are collected from the user agent, an
+    "<literal>Authentication</literal> request" object is built and then
+    presented to an
+    <interfacename>AuthenticationProvider</interfacename>.</para>
+
+    <para>The last player in the Spring Security authentication process is
+    an <literal>AuthenticationProvider</literal>. Quite simply, it is
+    responsible for taking an <literal>Authentication</literal> request
+    object and deciding whether or not it is valid. The provider will
+    either throw an exception or return a fully populated
+    <literal>Authentication</literal> object. Remember our good friends,
+    <literal>UserDetails</literal> and
+    <literal>UserDetailsService</literal>? If not, head back to the
+    previous section and refresh your memory. Most
+    <literal>AuthenticationProvider</literal>s will ask a
+    <literal>UserDetailsService</literal> to provide a
+    <literal>UserDetails</literal> object. As mentioned earlier, most
+    application will provide their own
+    <literal>UserDetailsService</literal>, although some will be able to
+    use the JDBC or in-memory implementation that ships with Spring
+    Security. The resultant <literal>UserDetails</literal> object - and
+    particularly the <literal>GrantedAuthority[]</literal>s contained
+    within the <literal>UserDetails</literal> object - will be used when
+    building the fully populated <literal>Authentication</literal>
+    object.</para>
+
+    <para>After the authentication mechanism receives back the
+    fully-populated <literal>Authentication</literal> object, it will deem
+    the request valid, put the <literal>Authentication</literal> into the
+    <literal>SecurityContextHolder</literal>, and cause the original
+    request to be retried (step seven above). If, on the other hand, the
+    <literal>AuthenticationProvider</literal> rejected the request, the
+    authentication mechanism will ask the user agent to retry (step two
+    above).</para>
+
+    <para>Whilst this describes the typical authentication workflow, the
+    good news is that Spring Security doesn't mind how you put an
+    <literal>Authentication</literal> inside the
+    <literal>SecurityContextHolder</literal>. The only critical
+    requirement is that the <literal>SecurityContextHolder</literal>
+    contains an <literal>Authentication</literal> that represents a
+    principal before the <literal>AbstractSecurityInterceptor</literal>
+    needs to authorize a request.</para>
+
+    <para>You can (and many users do) write their own filters or MVC
+    controllers to provide interoperability with authentication systems
+    that are not based on Spring Security. For example, you might be using
+    Container Managed Authentication which makes the current user
+    available from a ThreadLocal or JNDI location. Or you might work for a
+    company that has a legacy proprietary authentication system, which is
+    a corporate "standard" over which you have little control. In such
+    situations it's quite easy to get Spring Security to work, and still
+    provide authorization capabilities. All you need to do is write a
+    filter (or equivalent) that reads the third-party user information
+    from a location, build a Spring Security-specific Authentication
+    object, and put it onto the SecurityContextHolder. It's quite easy to
+    do this, and it is a fully-supported integration approach.</para>
+  </sect1>
+
+  <sect1 id="secure-objects">
+    <title>Secure Objects</title>
+
+    <para>If you're familiar with AOP, you'd be aware there are different
+    types of advice available: before, after, throws and around. An around
+    advice is very useful, because an advisor can elect whether or not to
+    proceed with a method invocation, whether or not to modify the
+    response, and whether or not to throw an exception. Spring Security
+    provides an around advice for method invocations as well as web
+    requests. We achieve an around advice for method invocations using AOP
+    Alliance, and we achieve an around advice for web requests using a
+    standard Filter.</para>
+
+    <para>For those not familiar with AOP, the key point to understand is
+    that Spring Security can help you protect method invocations as well
+    as web requests. Most people are interested in securing method
+    invocations on their services layer. This is because the services
+    layer is where most business logic resides in current-generation J2EE
+    applications (for clarification, the author disapproves of this design
+    and instead advocates properly encapsulated domain objects together
+    with the DTO, assembly, facade and transparent persistence patterns,
+    but as anemic domain objects is the present mainstream approach, we'll
+    talk about it here). If you just need to secure method invocations to
+    the services layer, using the Spring's standard AOP platform
+    (otherwise known as AOP Alliance) will be adequate. If you need to
+    secure domain objects directly, you will likely find that AspectJ is
+    worth considering.</para>
+
+    <para>You can elect to perform method authorization using AspectJ or
+    AOP Alliance, or you can elect to perform web request authorization
+    using filters. You can use zero, one, two or three of these approaches
+    together. The mainstream usage is to perform some web request
+    authorization, coupled with some AOP Alliance method invocation
+    authorization on the services layer.</para>
+
+    <para>Spring Security uses the term "secure object" to refer to any
+    object that can have security applied to it. Each secure object
+    supported by Spring Security has its own class, which is a subclass of
+    <literal>AbstractSecurityInterceptor</literal>. Importantly, by the
+    time the <literal>AbstractSecurityInterceptor</literal> is run, the
+    <literal>SecurityContextHolder</literal> will contain a valid
+    <literal>Authentication</literal> if the principal has been
+    authenticated.</para>
+
+    <para>The <literal>AbstractSecurityInterceptor</literal> provides a
+    consistent workflow for handling secure object requests. This workflow
+    includes looking up the "configuration attributes" associated with the
+    present request. A "configuration attribute" can be thought of as a
+    String that has special meaning to the classes used by
+    <literal>AbstractSecurityInterceptor</literal>. They're normally
+    configured against your <literal>AbstractSecurityInterceptor</literal>
+    using XML. Anyway, the <literal>AbstractSecurityInterceptor</literal>
+    will ask an <literal>AccessDecisionManager</literal> "here's the
+    configuration attributes, here's the current
+    <literal>Authentication</literal> object, and here's details of the
+    current request - is this particular principal allowed to perform this
+    particular operation?".</para>
+
+    <para>Assuming <literal>AccessDecisionManager</literal> decides to
+    allow the request, the <literal>AbstractSecurityInterceptor</literal>
+    will normally just proceed with the request. Having said that, on rare
+    occasions users may want to replace the
+    <literal>Authentication</literal> inside the
+    <literal>SecurityContext</literal> with a different
+    <literal>Authentication</literal>, which is handled by the
+    <literal>AccessDecisionManager</literal> calling a
+    <literal>RunAsManager</literal>. This might be useful in reasonably
+    unusual situations, such as if a services layer method needs to call a
+    remote system and present a different identity. Because Spring
+    Security automatically propagates security identity from one server to
+    another (assuming you're using a properly-configured RMI or
+    HttpInvoker remoting protocol client), this may be useful.</para>
+
+    <para>Following the secure object proceeding and then returning -
+    which may mean a method invocation completing or a filter chain
+    proceeding - the <literal>AbstractSecurityInterceptor</literal> gets
+    one final chance to handle the invocation. At this stage the
+    <literal>AbstractSecurityInterceptor</literal> is interested in
+    possibly modifying the return object. We might want this to happen
+    because an authorization decision couldn't be made "on the way in" to
+    a secure object invocation. Being highly pluggable,
+    <literal>AbstractSecurityInterceptor</literal> will pass control to an
+    <literal>AfterInvocationManager</literal> to actually modify the
+    object if needed. This class even can entirely replace the object, or
+    throw an exception, or not change it in any way.</para>
+
+    <para>Because <literal>AbstractSecurityInterceptor</literal> is the
+    central template class, it seems fitting that the first figure should
+    be devoted to it.</para>
+
+    <para><mediaobject>
+        <imageobject role="html">
+          <imagedata align="center"
+                     fileref="images/SecurityInterception.gif"
+                     format="GIF" />
+        </imageobject>
+
+        <imageobject role="fo">
+          <imagedata align="center"
+                     fileref="images/SecurityInterception.gif"
+                     format="GIF" />
+        </imageobject>
+
+        <caption>
+          <para>Figure 1: The key "secure object" model</para>
+        </caption>
+      </mediaobject></para>
+
+    <para>Only developers contemplating an entirely new way of
+    intercepting and authorizing requests would need to use secure objects
+    directly. For example, it would be possible to build a new secure
+    object to secure calls to a messaging system. Anything that requires
+    security and also provides a way of intercepting a call (like the AOP
+    around advice semantics) is capable of being made into a secure
+    object. Having said that, most Spring applications will simply use the
+    three currently supported secure object types (AOP Alliance
+    <literal>MethodInvocation</literal>, AspectJ
+    <literal>JoinPoint</literal> and web request
+    <literal>FilterInterceptor</literal>) with complete
+    transparency.</para>
+  </sect1>
+
+  <sect1 id="common-conclusion">
+    <title>Conclusion</title>
+
+    <para>Congratulations! You have enough of a high-level picture of
+    Spring Security to embark on your project. We've explored the shared
+    components, how authentication works, and reviewed the common
+    authorization concept of a "secure object". Everything that follows in
+    this reference guide may or may not apply to your particular needs,
+    and can be read in any order.</para>
+  </sect1>
+</chapter>

src/docbkx/x509-auth-provider.xml

@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="x509">
+<title>X509 Authentication</title>
+
+<sect1 id="x509-overview">
+    <title>Overview</title>
+    
+    <para>The most common use of X509 certificate authentication is in
+        verifying the identity of a server when using SSL, most commonly when
+        using HTTPS from a browser. The browser will automatically check that
+        the certificate presented by a server has been issued (ie digitally
+        signed) by one of a list of trusted certificate authorities which it
+        maintains.</para>
+    
+    <para>You can also use SSL with <quote>mutual authentication</quote>;
+        the server will then request a valid certificate from the client as
+        part of the SSL handshake. The server will authenticate the client by
+        checking that it's certificate is signed by an acceptable authority.
+        If a valid certificate has been provided, it can be obtained through
+        the servlet API in an application. Spring Security X509 module
+        extracts the certificate using a filter and passes it to the
+        configured X509 authentication provider to allow any additional
+        application-specific checks to be applied. It also maps the
+        certificate to an application user and loads that user's set of
+        granted authorities for use with the standard Spring Security
+        infrastructure.</para>
+    
+    <para>You should be familiar with using certificates and setting up
+        client authentication for your servlet container before attempting to
+        use it with Spring Security. Most of the work is in creating and
+        installing suitable certificates and keys. For example, if you're
+        using Tomcat then read the instructions here <ulink
+            url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
+        It's important that you get this working before trying it out with
+        Spring Security</para>
+</sect1>
+
+<sect1 id="x509-with-acegi">
+    <title>Using X509 with Spring Security</title>
+    
+    <para>With X509 authentication, there is no explicit login procedure
+        so the implementation is relatively simple; there is no need to
+        redirect requests in order to interact with the user. As a result,
+        some of the classes behave slightly differently from their equivalents
+        in other packages. For example, the default <quote>entry point</quote>
+        class, which is normally responsible for starting the authentication
+        process, is only invoked if the certificate is rejected and it always
+        returns an error to the user. With a suitable bean configuration, the
+        normal sequence of events is as follows <orderedlist>
+            <listitem>
+                <para>The <classname>X509ProcessingFilter</classname> extracts
+                    the certificate from the request and uses it as the credentials
+                    for an authentication request. The generated authentication
+                    request is an <classname>X509AuthenticationToken</classname>.
+                    The request is passed to the authentication manager.</para>
+            </listitem>
+            
+            <listitem>
+                <para>The <classname>X509AuthenticationProvider</classname>
+                    receives the token. Its main concern is to obtain the user
+                    information (in particular the user's granted authorities) that
+                    matches the certificate. It delegates this responsibility to an
+                    <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
+            </listitem>
+            
+            <listitem>
+                <para>The populator's single method,
+                    <methodname>getUserDetails(X509Certificate
+                        userCertificate)</methodname> is invoked. Implementations should
+                    return a <classname>UserDetails</classname> instance containing
+                    the array of <classname>GrantedAuthority</classname> objects for
+                    the user. This method can also choose to reject the certificate
+                    (for example if it doesn't contain a matching user name). In
+                    such cases it should throw a
+                    <exceptionname>BadCredentialsException</exceptionname>. A
+                    DAO-based implementation,
+                    <classname>DaoX509AuthoritiesPopulator</classname>, is provided
+                    which extracts the user's name from the subject <quote>common
+                        name</quote> (CN) in the certificate. It also allows you to set
+                    your own regular expression to match a different part of the
+                    subject's distinguished name. A UserDetailsService is used to
+                    load the user information.<!-- TODO: Give email matching as an example --></para>
+            </listitem>
+            
+            <listitem>
+                <para>If everything has gone smoothly then there should be a
+                    valid <classname>Authentication</classname> object in the secure
+                    context and the invocation will procede as normal. If no
+                    certificate was found, or the certificate was rejected, then the
+                    <classname>ExceptionTranslationFilter</classname> will invoke
+                    the <classname>X509ProcessingFilterEntryPoint</classname> which
+                    returns a 403 error (forbidden) to the user.</para>
+            </listitem>
+        </orderedlist></para>
+</sect1>
+
+<sect1 id="x509-config">
+    <title>Configuration</title>
+    
+    <para>There is a version of the <link
+        linkend="contacts-sample">Contacts Sample Application</link> which
+        uses X509. Copy the beans and filter setup from this as a starting
+        point for configuring your own application. A set of example
+        certificates is also included which you can use to configure your
+        server. These are <itemizedlist>
+            <listitem>
+                <para><filename>user.p12</filename>: A PKCS12 format file
+                    containing the client key and certificate. These should be
+                    installed in your browser. It maps to a use in the
+                    application.</para>
+            </listitem>
+            
+            <listitem>
+                <para><filename>server.p12</filename>: The server certificate
+                    and key for HTTPS connections.</para>
+            </listitem>
+            
+            <listitem>
+                <para><filename>ca.jks</filename>: A Java keystore containing
+                    the certificate for the authority which issued the user's
+                    certificate. This will be used by the container to validate
+                    client certificates.</para>
+            </listitem>
+        </itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
+        configuration in the <filename>server.xml</filename> file looks like
+        this <programlisting>
+            &lt;!-- SSL/TLS Connector configuration --&gt;
+            &lt;Connector port="8443" address="${jboss.bind.address}"
+            maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
+            scheme="https" secure="true"
+            sslProtocol = "TLS"
+            clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12"
+            keystoreType="PKCS12" keystorePass="password"
+            truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
+            truststoreType="JKS" truststorePass="password"
+            /&gt;
+            
+        </programlisting><parameter>clientAuth</parameter> can also be set to
+        <parameter>want</parameter> if you still want SSL connections to
+        succeed even if the client doesn't provide a certificate. Obviously
+        these clients won't be able to access any objects secured by Spring
+        Security (unless you use a non-X509 authentication mechanism, such as
+        BASIC authentication, to authenticate the user)</para>
+</sect1>
+</chapter>

src/docbkx/xml-auth-provider.xml

@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                         "http://www.docbook.org/xml/4.4/docbookx.dtd">
+
+<chapter id="x509">
+<title>X509 Authentication</title>
+
+<sect1 id="x509-overview">
+    <title>Overview</title>
+    
+    <para>The most common use of X509 certificate authentication is in
+        verifying the identity of a server when using SSL, most commonly when
+        using HTTPS from a browser. The browser will automatically check that
+        the certificate presented by a server has been issued (ie digitally
+        signed) by one of a list of trusted certificate authorities which it
+        maintains.</para>
+    
+    <para>You can also use SSL with <quote>mutual authentication</quote>;
+        the server will then request a valid certificate from the client as
+        part of the SSL handshake. The server will authenticate the client by
+        checking that it's certificate is signed by an acceptable authority.
+        If a valid certificate has been provided, it can be obtained through
+        the servlet API in an application. Spring Security X509 module
+        extracts the certificate using a filter and passes it to the
+        configured X509 authentication provider to allow any additional
+        application-specific checks to be applied. It also maps the
+        certificate to an application user and loads that user's set of
+        granted authorities for use with the standard Spring Security
+        infrastructure.</para>
+    
+    <para>You should be familiar with using certificates and setting up
+        client authentication for your servlet container before attempting to
+        use it with Spring Security. Most of the work is in creating and
+        installing suitable certificates and keys. For example, if you're
+        using Tomcat then read the instructions here <ulink
+            url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
+        It's important that you get this working before trying it out with
+        Spring Security</para>
+</sect1>
+
+<sect1 id="x509-with-acegi">
+    <title>Using X509 with Spring Security</title>
+    
+    <para>With X509 authentication, there is no explicit login procedure
+        so the implementation is relatively simple; there is no need to
+        redirect requests in order to interact with the user. As a result,
+        some of the classes behave slightly differently from their equivalents
+        in other packages. For example, the default <quote>entry point</quote>
+        class, which is normally responsible for starting the authentication
+        process, is only invoked if the certificate is rejected and it always
+        returns an error to the user. With a suitable bean configuration, the
+        normal sequence of events is as follows <orderedlist>
+            <listitem>
+                <para>The <classname>X509ProcessingFilter</classname> extracts
+                    the certificate from the request and uses it as the credentials
+                    for an authentication request. The generated authentication
+                    request is an <classname>X509AuthenticationToken</classname>.
+                    The request is passed to the authentication manager.</para>
+            </listitem>
+            
+            <listitem>
+                <para>The <classname>X509AuthenticationProvider</classname>
+                    receives the token. Its main concern is to obtain the user
+                    information (in particular the user's granted authorities) that
+                    matches the certificate. It delegates this responsibility to an
+                    <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
+            </listitem>
+            
+            <listitem>
+                <para>The populator's single method,
+                    <methodname>getUserDetails(X509Certificate
+                        userCertificate)</methodname> is invoked. Implementations should
+                    return a <classname>UserDetails</classname> instance containing
+                    the array of <classname>GrantedAuthority</classname> objects for
+                    the user. This method can also choose to reject the certificate
+                    (for example if it doesn't contain a matching user name). In
+                    such cases it should throw a
+                    <exceptionname>BadCredentialsException</exceptionname>. A
+                    DAO-based implementation,
+                    <classname>DaoX509AuthoritiesPopulator</classname>, is provided
+                    which extracts the user's name from the subject <quote>common
+                        name</quote> (CN) in the certificate. It also allows you to set
+                    your own regular expression to match a different part of the
+                    subject's distinguished name. A UserDetailsService is used to
+                    load the user information.<!-- TODO: Give email matching as an example --></para>
+            </listitem>
+            
+            <listitem>
+                <para>If everything has gone smoothly then there should be a
+                    valid <classname>Authentication</classname> object in the secure
+                    context and the invocation will procede as normal. If no
+                    certificate was found, or the certificate was rejected, then the
+                    <classname>ExceptionTranslationFilter</classname> will invoke
+                    the <classname>X509ProcessingFilterEntryPoint</classname> which
+                    returns a 403 error (forbidden) to the user.</para>
+            </listitem>
+        </orderedlist></para>
+</sect1>
+
+<sect1 id="x509-config">
+    <title>Configuration</title>
+    
+    <para>There is a version of the <link
+        linkend="contacts-sample">Contacts Sample Application</link> which
+        uses X509. Copy the beans and filter setup from this as a starting
+        point for configuring your own application. A set of example
+        certificates is also included which you can use to configure your
+        server. These are <itemizedlist>
+            <listitem>
+                <para><filename>user.p12</filename>: A PKCS12 format file
+                    containing the client key and certificate. These should be
+                    installed in your browser. It maps to a use in the
+                    application.</para>
+            </listitem>
+            
+            <listitem>
+                <para><filename>server.p12</filename>: The server certificate
+                    and key for HTTPS connections.</para>
+            </listitem>
+            
+            <listitem>
+                <para><filename>ca.jks</filename>: A Java keystore containing
+                    the certificate for the authority which issued the user's
+                    certificate. This will be used by the container to validate
+                    client certificates.</para>
+            </listitem>
+        </itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
+        configuration in the <filename>server.xml</filename> file looks like
+        this <programlisting>
+            &lt;!-- SSL/TLS Connector configuration --&gt;
+            &lt;Connector port="8443" address="${jboss.bind.address}"
+            maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
+            scheme="https" secure="true"
+            sslProtocol = "TLS"
+            clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12"
+            keystoreType="PKCS12" keystorePass="password"
+            truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
+            truststoreType="JKS" truststorePass="password"
+            /&gt;
+            
+        </programlisting><parameter>clientAuth</parameter> can also be set to
+        <parameter>want</parameter> if you still want SSL connections to
+        succeed even if the client doesn't provide a certificate. Obviously
+        these clients won't be able to access any objects secured by Spring
+        Security (unless you use a non-X509 authentication mechanism, such as
+        BASIC authentication, to authenticate the user)</para>
+</sect1>
+</chapter>