93 lines
6.2 KiB
XML
93 lines
6.2 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.docbook.org/xml/4.4/docbookx.dtd">
|
|
<chapter id="x509">
|
|
<title>X.509 Authentication</title>
|
|
<sect1 id="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 (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. Spring Security 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 Spring 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 Spring 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://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html"/>. It's important that
|
|
you get this working before trying it out with Spring Security</para>
|
|
</sect1>
|
|
<sect1>
|
|
<title>Adding X.509 Authentication to Your Web Application</title>
|
|
<para> Enabling X.509 client authentication is very straightforward. Just add the <literal
|
|
><x509/></literal> element to your http security namespace configuration. <programlisting><![CDATA[
|
|
<http>
|
|
...
|
|
<x509 subject-principal-regex="CN=(.*?)," user-service-ref="userService"/>
|
|
...
|
|
</http>]]>
|
|
</programlisting> The element has two optional attributes: <itemizedlist>
|
|
<listitem>
|
|
<para><literal>subject-principal-regex</literal>. The regular expression used to
|
|
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
|
|
>UserDetailsService</literal> to load the authorities for the
|
|
user.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>user-service-ref</literal>. This is the bean Id of the
|
|
<interfacename>UserDetailsService</interfacename> to be used with X.509.
|
|
It isn't needed if there is only one defined in your application
|
|
context.</para>
|
|
</listitem>
|
|
</itemizedlist> The <literal>subject-principal-regex</literal> should contain a single
|
|
group. For example the default expression "CN=(.*?)," matches the common name field. So
|
|
if the subject name in the certificate is "CN=Jimi Hendrix, OU=...", this will give a
|
|
user name of "Jimi Hendrix". The matches are case insensitive. So "emailAddress=(.?),"
|
|
will match "EMAILADDRESS=jimi@hendrix.org,CN=..." giving a user name "jimi@hendrix.org".
|
|
If the client presents a certificate and a valid username is successfully extracted,
|
|
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
|
|
then the security context will remain empty. This means that you can easily use X.509
|
|
authentication with other options such as a form-based login. </para>
|
|
</sect1>
|
|
<sect1 id="x509-ssl-config">
|
|
<title>Setting up SSL in Tomcat</title>
|
|
<para>There are some pre-generated certificates in the
|
|
<filename>samples/certificate</filename> directory in the Spring Security project.
|
|
You can use these to enable SSL for testing if you don't want to generate your own. The file
|
|
<filename>server.jks</filename> contains the server certificate, private key and the
|
|
issuing certificate authority certificate. There are also some client certificate files
|
|
for the users from the sample applications. You can install these in your browser to enable
|
|
SSL client authentication.
|
|
</para>
|
|
<para>
|
|
To run tomcat with SSL support, drop the <filename>server.jks</filename> file into the
|
|
tomcat <filename>conf</filename> directory and add the following connector to the
|
|
<filename>server.xml</filename> file
|
|
<programlisting><![CDATA[
|
|
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" scheme="https" secure="true"
|
|
clientAuth="true" sslProtocol="TLS"
|
|
keystoreFile="${catalina.home}/conf/server.jks"
|
|
keystoreType="JKS" keystorePass="password"
|
|
truststoreFile="${catalina.home}/conf/server.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.
|
|
Clients which don't present a certificate won't be able to access any objects secured by
|
|
Spring Security unless you use a non-X.509 authentication mechanism, such as form authentication.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|