SEC-701: Update X.509 Section

http://jira.springframework.org/browse/SEC-701

src/docbkx/x509-auth-provider.xml

@@ -1,134 +1,78 @@
 <?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}"
+    <title>X.509 Authentication</title>
+    <sect1 id="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 (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 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 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://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html"/>. It's important that
+            you get this working before trying it out with Spring Security</para>
+    </sect1>
+    <sect1>
+        <title>Adding X.509 Authentication to Your Web Application</title>
+        <para> Enabling X.509 client authentication is very straightforward. Just add the <literal
+                >&lt;x509/&gt;</literal> element to your http security namespace configuration. <programlisting><![CDATA[
+    <http>
+     ...
+        <x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>
+     ...
+    </http>]]>
+            </programlisting> The element has two optional attributes: <itemizedlist>
+                <listitem>
+                    <para><literal>subject-principal-regex</literal>. The regular expression used to
+                        extract a username from the certificate's subject name. The default value is
+                        shown above. This is the username which will be passed to the <literal
+                            >UserDetailsService</literal> to load the authorities for the
+                    user.</para>
+                </listitem>
+                <listitem>
+                    <para><literal>user-service-ref</literal>. This is the bean Id of the
+                            <interfacename>UserDetailsService</interfacename> to be used with X.509.
+                        It isn't needed if there is only one defined in your application
+                    context.</para>
+                </listitem>
+            </itemizedlist> The <literal>subject-principal-regex</literal> should contain a single
+            group. For example the default expression "CN=(.*?)," matches the common name field. So
+            if the subject name in the certificate is "CN=Jimi Hendrix, OU=...", this will give a
+            user name of "Jimi Hendrix". The matches are case insensitive. So "emailAddress=(.?),"
+            will match "EMAILADDRESS=jimi@hendrix.org,CN=..." giving a user name "jimi@hendrix.org".
+            If the client presents a certificate and a valid username is successfully extracted,
+            then there should be a valid <classname>Authentication</classname> object in the
+            security context. If no certificate is found, or no corresponding user could be found
+            then the security context will remain empty. This means that you can easily use X.509
+            authentication with other options such as a form-based login. </para>
+    </sect1>
+    <sect1 id="x509-config">
+        <title>Configuring Tomcat</title>
+        <para>There are some pre-generated certificates in the Spring Security 
+            <filename>samples/certificate</filename> directory which you can use to enable SSL. The file
+                <filename>server.jks</filename> contains the server certificate, private key and the
+            issuing certificate authority. There are also some client certificate files for the users from the
+            sample applications. You can install these in your browser to enable SSL client authentication.
+        </para>
+        <para>
+            To enable SSL in tomcat <filename>server.xml</filename> file looks like this
+                <programlisting><![CDATA[ 
+            <!-- SSL/TLS Connector configuration -->
+            <Connector port="8443" address="${jboss.bind.address}"
             maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
             scheme="https" secure="true"
             sslProtocol = "TLS"
@@ -136,13 +80,12 @@
             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>
+            /> ]]>
+                </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>