Cwikius-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added first draft of X509 docs

This commit is contained in:
Luke Taylor 2005-03-20 16:50:05 +00:00
parent a4210b5551
commit 4f697bee29
1 changed files with 101 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
doc/docbook/acegi.xml
View File

@ -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>