diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml
index abe8215cd2..b1550f069f 100644
--- a/doc/docbook/acegi.xml
+++ b/doc/docbook/acegi.xml
@@ -3811,6 +3811,107 @@ $CATALINA_HOME/bin/startup.sh
+
+ X.509 Authentication
+
+ Overview
+ 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.
+
+ You can also use SSL with mutual authentication;
+ 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.
+
+ 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 .
+ It's important that you get this working before trying it out with Acegi.
+
+
+
+ X.509 with Acegi Security
+ 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 entry point 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
+
+ The X509ProcessingFilter extracts the certificate
+ from the request and uses it as the credentials for an authentication request. The
+ request is an X509AuthenticationToken. The request is passed to
+ the authentication manager.
+ The X509AuthenticationProvider 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 X509AuthoritiesPopulator..
+ The populator's single method,
+ getUserDetails(X509Certificate userCertificate) is invoked.
+ Implementations should return a UserDetails instance containing
+ the set of GrantedAuthority 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 BadCredentialsException. A dao-based
+ implementation DaoX509AuthoritiesPopulator is provided which extracts
+ the user's name from the subject common name 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 AuthenticationDao to load the user information.
+
+
+ If everything has gone smoothly then there should be a valid
+ Authentication object in the secure context and the invocation will procede
+ as normal. If no certificate was found, or the certificate was rejected, then the
+ SecurityEnforcementFilter will invoke the
+ X509ProcessingFilterEntryPoint which returns a 403 error to the
+ user.
+
+
+
+
+ Configuring the X.509 Provider
+ There is a version of the contacts sample application 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
+
+
+ marissa.p12 A PKCS12 format file containing the client key and certificate. These should
+ be installed in your browser. It maps to the user marissa in the application.
+ server.p12 The server certificate and key for HTTPS connections.
+ ca.jks 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.
+
+
+ For JBoss 3.2.7 (with Tomcat 5.0), the SSL configuration in the server.xml file looks like this
+
+ <!-- SSL/TLS Connector configuration -->
+ <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"
+ />
+
+ clientAuth can also be set to want 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.
+
+
+
+
+
Channel Security