Minor consistency changes.
This commit is contained in:
Ben Alex
parent
f1f5e687ee
commit
f510989cbb
|
|
@ -26,7 +26,7 @@
|
|||
|
||||
<subtitle>Reference Documentation</subtitle>
|
||||
|
||||
<releaseinfo>0.8.0</releaseinfo>
|
||||
<releaseinfo>0.8.1</releaseinfo>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
|
|
@ -2679,7 +2679,7 @@ key: A private key to prevent modification of the nonce token
|
|||
login to take place. Acegi 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>
|
||||
cookie-based tokens.</para>
|
||||
|
||||
<para>Remember-me authentication is not used with digest or basic
|
||||
authentication, given they are often not used with
|
||||
|
|
@ -3812,106 +3812,158 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
|
|||
</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
|
||||
<title>X509 Authentication</title>
|
||||
|
||||
<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>
|
||||
<!-- 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"
|
||||
/>
|
||||
</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>
|
||||
|
||||
<sect2 id="security-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. The Acegi 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 Acegi 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 Acegi 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
|
||||
Acegi Security.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="security-x509-details">
|
||||
<title>X509 with Acegi 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. An
|
||||
<classname>AuthenticationDao</classname> 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>SecurityEnforcementFilter</classname> will invoke the
|
||||
<classname>X509ProcessingFilterEntryPoint</classname> which
|
||||
returns a 403 error (forbidden) to the user.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
</orderedlist></para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="security-x509-config">
|
||||
<title>Configuring the X509 Provider</title>
|
||||
|
||||
<para>There is a version of the <link
|
||||
linkend="security-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>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><!-- 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"
|
||||
/></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 Acegi
|
||||
Security (unless you use a non-X509 authentication mechanism, such as
|
||||
BASIC authentication, to authenticate the user).</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
|
||||
<sect1 id="security-channels">
|
||||
<title>Channel Security</title>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue