Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-06-28 14:52:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

SEC-701: Update X.509 Section

Browse Source 
http://jira.springframework.org/browse/SEC-701
This commit is contained in:
Luke Taylor 2008-03-09 13:24:13 +00:00
parent bd59e410e3
commit 8165e1d37f
1 changed files with 80 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

217
src/docbkx/x509-auth-provider.xml
View File

@ -1,134 +1,78 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.docbook.org/xml/4.4/docbookx.dtd"> "http://www.docbook.org/xml/4.4/docbookx.dtd">
<chapter id="x509"> <chapter id="x509">
<title>X509 Authentication</title> <title>X.509 Authentication</title>
<sect1 id="x509-overview">
<sect1 id="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 HTTPS from a browser. The browser
<para>The most common use of X509 certificate authentication is in will automatically check that the certificate presented by a server has been issued (ie
verifying the identity of a server when using SSL, most commonly when digitally signed) by one of a list of trusted certificate authorities which it
using HTTPS from a browser. The browser will automatically check that maintains.</para>
the certificate presented by a server has been issued (ie digitally <para>You can also use SSL with <quote>mutual authentication</quote>; the server will then
signed) by one of a list of trusted certificate authorities which it request a valid certificate from the client as part of the SSL handshake. The server
maintains.</para> 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
<para>You can also use SSL with <quote>mutual authentication</quote>; through the servlet API in an application. Spring Security X.509 module extracts the
the server will then request a valid certificate from the client as certificate using a filter and passes it to the configured X.509 authentication provider
part of the SSL handshake. The server will authenticate the client by to allow any additional application-specific checks to be applied. It also maps the
checking that it's certificate is signed by an acceptable authority. certificate to an application user and loads that user's set of granted authorities for
If a valid certificate has been provided, it can be obtained through use with the standard Spring Security infrastructure.</para>
the servlet API in an application. Spring Security X509 module <para>You should be familiar with using certificates and setting up client authentication
extracts the certificate using a filter and passes it to the for your servlet container before attempting to use it with Spring Security. Most of the
configured X509 authentication provider to allow any additional work is in creating and installing suitable certificates and keys. For example, if
application-specific checks to be applied. It also maps the you're using Tomcat then read the instructions here <ulink
certificate to an application user and loads that user's set of url="http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html"/>. It's important that
granted authorities for use with the standard Spring Security you get this working before trying it out with Spring Security</para>
infrastructure.</para> </sect1>
<sect1>
<para>You should be familiar with using certificates and setting up <title>Adding X.509 Authentication to Your Web Application</title>
client authentication for your servlet container before attempting to <para> Enabling X.509 client authentication is very straightforward. Just add the <literal
use it with Spring Security. Most of the work is in creating and >&lt;x509/&gt;</literal> element to your http security namespace configuration. <programlisting><![CDATA[
installing suitable certificates and keys. For example, if you're <http>
using Tomcat then read the instructions here <ulink ...
url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>. <x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>
It's important that you get this working before trying it out with ...
Spring Security</para> </http>]]>
</sect1> </programlisting> The element has two optional attributes: <itemizedlist>
<listitem>
<sect1 id="x509-with-acegi"> <para><literal>subject-principal-regex</literal>. The regular expression used to
<title>Using X509 with Spring Security</title> extract a username from the certificate's subject name. The default value is
shown above. This is the username which will be passed to the <literal
<para>With X509 authentication, there is no explicit login procedure >UserDetailsService</literal> to load the authorities for the
so the implementation is relatively simple; there is no need to user.</para>
redirect requests in order to interact with the user. As a result, </listitem>
some of the classes behave slightly differently from their equivalents <listitem>
in other packages. For example, the default <quote>entry point</quote> <para><literal>user-service-ref</literal>. This is the bean Id of the
class, which is normally responsible for starting the authentication <interfacename>UserDetailsService</interfacename> to be used with X.509.
process, is only invoked if the certificate is rejected and it always It isn't needed if there is only one defined in your application
returns an error to the user. With a suitable bean configuration, the context.</para>
normal sequence of events is as follows <orderedlist> </listitem>
<listitem> </itemizedlist> The <literal>subject-principal-regex</literal> should contain a single
<para>The <classname>X509ProcessingFilter</classname> extracts group. For example the default expression "CN=(.*?)," matches the common name field. So
the certificate from the request and uses it as the credentials if the subject name in the certificate is "CN=Jimi Hendrix, OU=...", this will give a
for an authentication request. The generated authentication user name of "Jimi Hendrix". The matches are case insensitive. So "emailAddress=(.?),"
request is an <classname>X509AuthenticationToken</classname>. will match "EMAILADDRESS=jimi@hendrix.org,CN=..." giving a user name "jimi@hendrix.org".
The request is passed to the authentication manager.</para> If the client presents a certificate and a valid username is successfully extracted,
</listitem> then there should be a valid <classname>Authentication</classname> object in the
security context. If no certificate is found, or no corresponding user could be found
<listitem> then the security context will remain empty. This means that you can easily use X.509
<para>The <classname>X509AuthenticationProvider</classname> authentication with other options such as a form-based login. </para>
receives the token. Its main concern is to obtain the user </sect1>
information (in particular the user's granted authorities) that <sect1 id="x509-config">
matches the certificate. It delegates this responsibility to an <title>Configuring Tomcat</title>
<interfacename>X509AuthoritiesPopulator</interfacename>.</para> <para>There are some pre-generated certificates in the Spring Security
</listitem> <filename>samples/certificate</filename> directory which you can use to enable SSL. The file
<filename>server.jks</filename> contains the server certificate, private key and the
<listitem> issuing certificate authority. There are also some client certificate files for the users from the
<para>The populator's single method, sample applications. You can install these in your browser to enable SSL client authentication.
<methodname>getUserDetails(X509Certificate </para>
userCertificate)</methodname> is invoked. Implementations should <para>
return a <classname>UserDetails</classname> instance containing To enable SSL in tomcat <filename>server.xml</filename> file looks like this
the array of <classname>GrantedAuthority</classname> objects for <programlisting><![CDATA[
the user. This method can also choose to reject the certificate <!-- SSL/TLS Connector configuration -->
(for example if it doesn't contain a matching user name). In <Connector port="8443" address="${jboss.bind.address}"
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. A UserDetailsService 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>ExceptionTranslationFilter</classname> will invoke
the <classname>X509ProcessingFilterEntryPoint</classname> which
returns a 403 error (forbidden) to the user.</para>
</listitem>
</orderedlist></para>
</sect1>
<sect1 id="x509-config">
<title>Configuration</title>
<para>There is a version of the <link
linkend="contacts-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>user.p12</filename>: A PKCS12 format file
containing the client key and certificate. These should be
installed in your browser. It maps to a use 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 the user'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" maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
scheme="https" secure="true" scheme="https" secure="true"
sslProtocol = "TLS" sslProtocol = "TLS"
@ -136,13 +80,12 @@
keystoreType="PKCS12" keystorePass="password" keystoreType="PKCS12" keystorePass="password"
truststoreFile="${jboss.server.home.dir}/conf/ca.jks" truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
truststoreType="JKS" truststorePass="password" truststoreType="JKS" truststorePass="password"
/&gt; /> ]]>
</programlisting>
</programlisting><parameter>clientAuth</parameter> can also be set to <parameter>clientAuth</parameter> can also be set to <parameter>want</parameter> if you still
<parameter>want</parameter> if you still want SSL connections to want SSL connections to succeed even if the client doesn't provide a certificate.
succeed even if the client doesn't provide a certificate. Obviously Obviously these clients won't be able to access any objects secured by Spring Security
these clients won't be able to access any objects secured by Spring (unless you use a non-X509 authentication mechanism, such as BASIC authentication, to
Security (unless you use a non-X509 authentication mechanism, such as authenticate the user)</para>
BASIC authentication, to authenticate the user)</para> </sect1>
</sect1> </chapter>
</chapter>