Added first draft of X509 docs

doc/docbook/acegi.xml

@@ -3811,6 +3811,107 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
       </sect2>
     </sect1>
 
+    <sect1 id="security-x509">
+        <title>X.509 Authentication</title>
+        <sect2 id="security-x509-overview">
+            <title>Overview</title>
+            <para>The most common use of X.509 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 (i.e. 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.
+                The Acegi X.509 module extracts the certificate using a filter and passes it to the
+                configured X.509 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 Acegi 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 Acegi. 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"/>.
+                It's important that you get this working before trying it out with Acegi.
+            </para>            
+        </sect2>
+        <sect2 id="security-x509-details">
+            <title>X.509 with Acegi Security</title>
+            <para>With X.509 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
+                    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. It's main concern is to obtain the user information (in particular the user's
+                    granted authorities) which match 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 set 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).
+                    It should then 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> in the certificate. It also allows
+                    you to set your own regular expression to match a different part of the subject distinguished
+                    name. It uses an <classname>AuthenticationDao</classname> 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>SecurityEnforcementFilter</classname> will invoke the 
+                    <classname>X509ProcessingFilterEntryPoint</classname> which returns a 403 error to the
+                    user.</para></listitem>
+                </orderedlist>                
+            </para>
+        </sect2>
+        <sect2 id="security-x509-config">
+            <title>Configuring the X.509 Provider</title>
+            <para>There is a version of the <link linkend="security-sample">contacts sample application</link> which uses X.509.
+            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>marissa.p12</filename> A PKCS12 format file containing the client key and certificate. These should
+                be installed in your browser. It maps to the user <quote>marissa</quote> 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 marissa'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=&quot;8443&quot; address=&quot;${jboss.bind.address}&quot;
+           maxThreads=&quot;100&quot; minSpareThreads=&quot;5&quot; maxSpareThreads=&quot;15&quot;
+           scheme=&quot;https&quot; secure=&quot;true&quot;
+           sslProtocol = &quot;TLS&quot;
+           clientAuth=&quot;true&quot; keystoreFile=&quot;${jboss.server.home.dir}/conf/server.p12&quot;
+           keystoreType=&quot;PKCS12&quot; keystorePass=&quot;password&quot;
+           truststoreFile=&quot;${jboss.server.home.dir}/conf/ca.jks&quot;
+           truststoreType=&quot;JKS&quot; truststorePass=&quot;password&quot;
+      /&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 Acegi-secured
+            objects.
+            </para>
+        </sect2>
+        
+    </sect1>
+     
     <sect1 id="security-channels">
       <title>Channel Security</title>