|
|
@@ -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
|
|
|
-
|
|
|
- <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>
|
|
|
-
|
|
|
+ <title>X509 Authentication</title>
|
|
|
+
|
|
|
+ <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>
|
|
|
|
Ben Alex