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

Minor consistency changes.

1.0.x
Ben Alex 21 years ago
parent
f1f5e687ee
commit
f510989cbb
1 changed files with 153 additions and 101 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 254
      doc/docbook/acegi.xml

254
doc/docbook/acegi.xml
Unescape 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>
@ -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 login to take place. Acegi Security provides the necessary hooks so
that such operations can take place, along with providing a concrete that such operations can take place, along with providing a concrete
implementation that uses hashing to preserve the security of 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 <para>Remember-me authentication is not used with digest or basic
authentication, given they are often not used with authentication, given they are often not used with
@ -3812,106 +3812,158 @@ $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">
<title>Overview</title> <sect2 id="security-x509-overview">
<para>The most common use of X.509 certificate authentication is <title>Overview</title>
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 <para>The most common use of X509 certificate authentication is in
certificate presented by a server has been issued (i.e. digitally verifying the identity of a server when using SSL, most commonly when
signed) by one of a list of trusted certificate authorities which using HTTPS from a browser. The browser will automatically check that
it maintains. the certificate presented by a server has been issued (ie digitally
</para> signed) by one of a list of trusted certificate authorities which it
<para>You can also use SSL with <quote>mutual authentication</quote>; maintains.</para>
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 <para>You can also use SSL with <quote>mutual authentication</quote>;
that it's certificate is signed by an acceptable authority. If a valid certificate the server will then request a valid certificate from the client as
has been provided, it can be obtained through the servlet API in an application. part of the SSL handshake. The server will authenticate the client by
The Acegi X.509 module extracts the certificate using a filter and passes it to the checking that it's certificate is signed by an acceptable authority.
configured X.509 authentication provider to allow any additional application-specific If a valid certificate has been provided, it can be obtained through
checks to be applied. It also maps the certificate to an application user and loads that the servlet API in an application. The Acegi Security X509 module
user's set of granted authorities for use with the standard Acegi infrastructure. extracts the certificate using a filter and passes it to the
</para> configured X509 authentication provider to allow any additional
<para>You should be familiar with using certificates and setting up client authentication for your application-specific checks to be applied. It also maps the
servlet container before attempting to use it with Acegi. Most of the work is in certificate to an application user and loads that user's set of
creating and installing suitable certificates and keys. For example, if you're using Tomcat then granted authorities for use with the standard Acegi Security
read the instructions here <ulink url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"/>. infrastructure.</para>
It's important that you get this working before trying it out with Acegi.
</para> <para>You should be familiar with using certificates and setting up
</sect2> client authentication for your servlet container before attempting to
<sect2 id="security-x509-details"> use it with Acegi Security. Most of the work is in creating and
<title>X.509 with Acegi Security</title> installing suitable certificates and keys. For example, if you're
<para>With X.509 authentication, there is no explicit login procedure so the implementation using Tomcat then read the instructions here <ulink
is relatively simple; there is no need to redirect requests in order to interact with the url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
user. As a result, some of the classes behave slightly differently from their equivalents in other packages. It's important that you get this working before trying it out with
For example, the default <quote>entry point</quote> class, which is normally responsible for starting the authentication Acegi Security.</para>
process, is only invoked if the certificate is rejected and it always returns an error to the user. </sect2>
With a suitable bean configuration, the normal sequence of events is as follows
<orderedlist> <sect2 id="security-x509-details">
<listitem><para>The <classname>X509ProcessingFilter</classname> extracts the certificate <title>X509 with Acegi Security</title>
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 <para>With X509 authentication, there is no explicit login procedure
the authentication manager.</para></listitem> so the implementation is relatively simple; there is no need to
<listitem><para>The <classname>X509AuthenticationProvider</classname> receives redirect requests in order to interact with the user. As a result,
the token. It's main concern is to obtain the user information (in particular the user's some of the classes behave slightly differently from their equivalents
granted authorities) which match the certificate. It delegates this responsibility in other packages. For example, the default <quote>entry point</quote>
to an <interfacename>X509AuthoritiesPopulator</interfacename>.</para></listitem>. class, which is normally responsible for starting the authentication
<listitem><para>The populator's single method, process, is only invoked if the certificate is rejected and it always
<methodname>getUserDetails(X509Certificate userCertificate)</methodname> is invoked. returns an error to the user. With a suitable bean configuration, the
Implementations should return a <classname>UserDetails</classname> instance containing normal sequence of events is as follows <orderedlist>
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 <listitem>
implementation <classname>DaoX509AuthoritiesPopulator</classname> is provided which extracts <para>The <classname>X509ProcessingFilter</classname> extracts
the user's name from the subject <quote>common name</quote> in the certificate. It also allows the certificate from the request and uses it as the credentials
you to set your own regular expression to match a different part of the subject distinguished for an authentication request. The generated authentication
name. It uses an <classname>AuthenticationDao</classname> to load the user information. request is an <classname>X509AuthenticationToken</classname>.
<!-- TODO: Give email matching as an example --> The request is passed to the authentication manager.</para>
</para></listitem> </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 <listitem>
<classname>X509ProcessingFilterEntryPoint</classname> which returns a 403 error to the <para>The <classname>X509AuthenticationProvider</classname>
user.</para></listitem> receives the token. Its main concern is to obtain the user
</orderedlist> information (in particular the user's granted authorities) that
</para> matches the certificate. It delegates this responsibility to an
</sect2> <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
<sect2 id="security-x509-config"> </listitem>
<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 <listitem>
<para>The populator's single method,
<itemizedlist> <methodname>getUserDetails(X509Certificate
<listitem><para><filename>marissa.p12</filename> A PKCS12 format file containing the client key and certificate. These should userCertificate)</methodname> is invoked. Implementations should
be installed in your browser. It maps to the user <quote>marissa</quote> in the application.</para></listitem> return a <classname>UserDetails</classname> instance containing
<listitem><para><filename>server.p12</filename> The server certificate and key for HTTPS connections.</para></listitem> the array of <classname>GrantedAuthority</classname> objects for
<listitem><para><filename>ca.jks</filename> A Java keystore containing the certificate for the authority which issued marissa's the user. This method can also choose to reject the certificate
certificate. This will be used by the container to validate client certificates.</para></listitem> (for example if it doesn't contain a matching user name). In
</itemizedlist> such cases it should throw a
<exceptionname>BadCredentialsException</exceptionname>. A
For JBoss 3.2.7 (with Tomcat 5.0), the SSL configuration in the <filename>server.xml</filename> file looks like this DAO-based implementation,
<programlisting> <classname>DaoX509AuthoritiesPopulator</classname>, is provided
&lt;!-- SSL/TLS Connector configuration --&gt; which extracts the user's name from the subject <quote>common
&lt;Connector port=&quot;8443&quot; address=&quot;${jboss.bind.address}&quot; name</quote> (CN) in the certificate. It also allows you to set
maxThreads=&quot;100&quot; minSpareThreads=&quot;5&quot; maxSpareThreads=&quot;15&quot; your own regular expression to match a different part of the
scheme=&quot;https&quot; secure=&quot;true&quot; subject's distinguished name. An
sslProtocol = &quot;TLS&quot; <classname>AuthenticationDao</classname> is used to load the
clientAuth=&quot;true&quot; keystoreFile=&quot;${jboss.server.home.dir}/conf/server.p12&quot; user information. <!-- TODO: Give email matching as an example --></para>
keystoreType=&quot;PKCS12&quot; keystorePass=&quot;password&quot; </listitem>
truststoreFile=&quot;${jboss.server.home.dir}/conf/ca.jks&quot;
truststoreType=&quot;JKS&quot; truststorePass=&quot;password&quot;
/&gt;
</programlisting> <listitem>
<parameter>clientAuth</parameter> can also be set to <parameter>want</parameter> if you still want SSL connections to <para>If everything has gone smoothly then there should be a
succeed even if the client doesn't provide a certificate. Obviously these clients won't be able to access any Acegi-secured valid <classname>Authentication</classname> object in the secure
objects. context and the invocation will procede as normal. If no
</para> certificate was found, or the certificate was rejected, then the
</sect2> <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>&lt;!-- SSL/TLS Connector configuration --&gt;
&lt;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"
/&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>
</sect1> </sect1>
<sect1 id="security-channels"> <sect1 id="security-channels">
<title>Channel Security</title> <title>Channel Security</title>

Write Preview
Loading…
Cancel
Save