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

Minor consistency changes.

This commit is contained in:
Ben Alex 2005-03-20 23:09:56 +00:00
parent f1f5e687ee
commit f510989cbb
1 changed files with 152 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

228
doc/docbook/acegi.xml
View File

@ -26,7 +26,7 @@
<subtitle>Reference Documentation</subtitle> <subtitle>Reference Documentation</subtitle>
<releaseinfo>0.8.0</releaseinfo> <releaseinfo>0.8.1</releaseinfo>
<authorgroup> <authorgroup>
<author> <author>
@ -3812,104 +3812,156 @@ $CATALINA_HOME/bin/startup.sh</programlisting></para>
</sect1> </sect1>
<sect1 id="security-x509"> <sect1 id="security-x509">
<title>X.509 Authentication</title> <title>X509 Authentication</title>
<sect2 id="security-x509-overview"> <sect2 id="security-x509-overview">
<title>Overview</title> <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 <para>The most common use of X509 certificate authentication is in
HTTPS from a browser. The browser will automatically check that the verifying the identity of a server when using SSL, most commonly when
certificate presented by a server has been issued (i.e. digitally using HTTPS from a browser. The browser will automatically check that
signed) by one of a list of trusted certificate authorities which the certificate presented by a server has been issued (ie digitally
it maintains. signed) by one of a list of trusted certificate authorities which it
</para> maintains.</para>
<para>You can also use SSL with <quote>mutual authentication</quote>; <para>You can also use SSL with <quote>mutual authentication</quote>;
the server will then request a valid certificate from the client the server will then request a valid certificate from the client as
as part of the SSL handshake. The server will authenticate the client by checking part of the SSL handshake. The server will authenticate the client by
that it's certificate is signed by an acceptable authority. If a valid certificate checking that it's certificate is signed by an acceptable authority.
has been provided, it can be obtained through the servlet API in an application. If a valid certificate has been provided, it can be obtained through
The Acegi X.509 module extracts the certificate using a filter and passes it to the the servlet API in an application. The Acegi Security X509 module
configured X.509 authentication provider to allow any additional application-specific extracts the certificate using a filter and passes it to the
checks to be applied. It also maps the certificate to an application user and loads that configured X509 authentication provider to allow any additional
user's set of granted authorities for use with the standard Acegi infrastructure. application-specific checks to be applied. It also maps the
</para> certificate to an application user and loads that user's set of
<para>You should be familiar with using certificates and setting up client authentication for your granted authorities for use with the standard Acegi Security
servlet container before attempting to use it with Acegi. Most of the work is in infrastructure.</para>
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"/>. <para>You should be familiar with using certificates and setting up
It's important that you get this working before trying it out with Acegi. client authentication for your servlet container before attempting to
</para> 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>
<sect2 id="security-x509-details"> <sect2 id="security-x509-details">
<title>X.509 with Acegi Security</title> <title>X509 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 <para>With X509 authentication, there is no explicit login procedure
user. As a result, some of the classes behave slightly differently from their equivalents in other packages. so the implementation is relatively simple; there is no need to
For example, the default <quote>entry point</quote> class, which is normally responsible for starting the authentication redirect requests in order to interact with the user. As a result,
process, is only invoked if the certificate is rejected and it always returns an error to the user. some of the classes behave slightly differently from their equivalents
With a suitable bean configuration, the normal sequence of events is as follows in other packages. For example, the default <quote>entry point</quote>
<orderedlist> class, which is normally responsible for starting the authentication
<listitem><para>The <classname>X509ProcessingFilter</classname> extracts the certificate process, is only invoked if the certificate is rejected and it always
from the request and uses it as the credentials for an authentication request. The returns an error to the user. With a suitable bean configuration, the
request is an <classname>X509AuthenticationToken</classname>. The request is passed to normal sequence of events is as follows <orderedlist>
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 <listitem>
granted authorities) which match the certificate. It delegates this responsibility <para>The <classname>X509ProcessingFilter</classname> extracts
to an <interfacename>X509AuthoritiesPopulator</interfacename>.</para></listitem>. the certificate from the request and uses it as the credentials
<listitem><para>The populator's single method, for an authentication request. The generated authentication
<methodname>getUserDetails(X509Certificate userCertificate)</methodname> is invoked. request is an <classname>X509AuthenticationToken</classname>.
Implementations should return a <classname>UserDetails</classname> instance containing The request is passed to the authentication manager.</para>
the set of <classname>GrantedAuthority</classname> objects for the user. This method can </listitem>
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 <listitem>
you to set your own regular expression to match a different part of the subject distinguished <para>The <classname>X509AuthenticationProvider</classname>
name. It uses an <classname>AuthenticationDao</classname> to load the user information. receives the token. Its main concern is to obtain the user
<!-- TODO: Give email matching as an example --> information (in particular the user's granted authorities) that
</para></listitem> matches the certificate. It delegates this responsibility to an
<listitem><para>If everything has gone smoothly then there should be a valid <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
<classname>Authentication</classname> object in the secure context and the invocation will procede </listitem>
as normal. If no certificate was found, or the certificate was rejected, then the
.
<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>SecurityEnforcementFilter</classname> will invoke the
<classname>X509ProcessingFilterEntryPoint</classname> which returns a 403 error to the <classname>X509ProcessingFilterEntryPoint</classname> which
user.</para></listitem> returns a 403 error (forbidden) to the user.</para>
</orderedlist> </listitem>
</para>
</orderedlist></para>
</sect2> </sect2>
<sect2 id="security-x509-config"> <sect2 id="security-x509-config">
<title>Configuring the X.509 Provider</title> <title>Configuring the X509 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> <para>There is a version of the <link
<listitem><para><filename>marissa.p12</filename> A PKCS12 format file containing the client key and certificate. These should linkend="security-sample">contacts sample application</link> which
be installed in your browser. It maps to the user <quote>marissa</quote> in the application.</para></listitem> uses X509. Copy the beans and filter setup from this as a starting
<listitem><para><filename>server.p12</filename> The server certificate and key for HTTPS connections.</para></listitem> point for configuring your own application. A set of example
<listitem><para><filename>ca.jks</filename> A Java keystore containing the certificate for the authority which issued marissa's certificates is also included which you can use to configure your
certificate. This will be used by the container to validate client certificates.</para></listitem> server. These are <itemizedlist>
</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>
For JBoss 3.2.7 (with Tomcat 5.0), the SSL configuration in the <filename>server.xml</filename> file looks like this <listitem>
<programlisting> <para><filename>server.p12</filename>: The server certificate
&lt;!-- SSL/TLS Connector configuration --&gt; and key for HTTPS connections.</para>
&lt;Connector port=&quot;8443&quot; address=&quot;${jboss.bind.address}&quot; </listitem>
maxThreads=&quot;100&quot; minSpareThreads=&quot;5&quot; maxSpareThreads=&quot;15&quot;
scheme=&quot;https&quot; secure=&quot;true&quot; <listitem>
sslProtocol = &quot;TLS&quot; <para><filename>ca.jks</filename>: A Java keystore containing
clientAuth=&quot;true&quot; keystoreFile=&quot;${jboss.server.home.dir}/conf/server.p12&quot; the certificate for the authority which issued marissa's
keystoreType=&quot;PKCS12&quot; keystorePass=&quot;password&quot; certificate. This will be used by the container to validate
truststoreFile=&quot;${jboss.server.home.dir}/conf/ca.jks&quot; client certificates.</para>
truststoreType=&quot;JKS&quot; truststorePass=&quot;password&quot; </listitem>
/&gt; </itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
</programlisting> configuration in the <filename>server.xml</filename> file looks like
<parameter>clientAuth</parameter> can also be set to <parameter>want</parameter> if you still want SSL connections to this <programlisting>&lt;!-- SSL/TLS Connector configuration --&gt;
succeed even if the client doesn't provide a certificate. Obviously these clients won't be able to access any Acegi-secured &lt;Connector port="8443" address="${jboss.bind.address}"
objects. maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
</para> 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"
/&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 Acegi
Security (unless you use a non-X509 authentication mechanism, such as
BASIC authentication, to authenticate the user).</para>
</sect2> </sect2>
</sect1> </sect1>
<sect1 id="security-channels"> <sect1 id="security-channels">