X.509 Certificates

Owned by ScottS
Last updated: Jun 04, 2009Version comment

Including the Dependency

In your pom.xml for your web application, include the following dependency:

<dependency>
   <groupId>org.jasig.cas.server</groupId>
   <artifactId>cas-server-authentication-x509</artifactId>
   <version>${cas.version}</version>
   <scope>runtime</scope>
   <type>jar</type>
</dependency>

Replace the cas version with the appropriate version number.

Modifying the Spring Web Flow

Setting up the Spring Configuration

Setting up Containers

Tomcat

Anything said here extends the Apache reference for SSL under Tomcat found at http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html;(this is the 5.5 version, but the SSL configuration is the same on all Tomcat releases).

The Tomcat server is configured in TOMCAT_HOME/conf/server.xml with one or more <Connector> elements. Each of these elements defines one port number on which Tomcat will listen for requests. Connectors that support SSL are configured with one or two files that represent a collection of X.509 certificates.

The keystoreFile is a collection of X.509 certificates one of which Tomcat will use to identify itself to Browsers. This certificate contains the DNS name of the server on which Tomcat is running which the HTTP client will have used as the servername part of the URL. It is possible to use a file that contains multiple certificates (in which case Tomcat will use the certificate stored under the alias "Tomcat" or, if that is not found, will use the first certificate it finds that also has an associated private key). However, to assure that no mistakes are made it is sensible practice to use a file that has only the one host certificate, plus of course its private key and chain of parent Certificate Authorities.

The truststoreFile is a collection of X.509 certificates representing Certificate Authorities from which Tomcat is willing to accept User certificates. Since the keystoreFile contains the CA that issued the certificate identifying the server, the truststoreFile and keystoreFile could be the same in a CAS configuration where the URL (actually the port) that uses X.509 authentication is not the well know widely recognized URL for interactive (userid/password form) login, and therefore the only CA that it trusts is the institutional internal CA.

However, the recommended strategy if you are planning to support both X.509 and userid/password validation through the same port is to put a public (VeriSign, Thawte) certificate for this server in the keystoreFile, but then put only the institutional internal CA certificate in the truststoreFile. Logically and in all the documentation, the Certificate Authority that issues the certificate to the Server which the Browser trusts is completely and logically independent of the Certificate Authority that issues the certificate to the User which the Server then trusts. Java keeps them separate, Tomcat keeps them separate, and Browsers should not be confused if, during SSL negotation, the Server requests a User certificate from a CA other than the one that issued the Server's own identifying certificate. In this configuration, the Server issues a public certificate every browser will accept, and the Browser is strongly urged to send only a private institutional certificate that can be mapped to a Principal name.

If you previously configured CAS without X.509 authentication, then you probably have the keystoreFile already configured and loaded with a certificate identifying this server. All you need to add is the truststoreFile part.

The configured connector will look something like:

<!-- Define a SSL HTTP/1.1 Connector on port 443 -->
<Connector port="443" maxHttpHeaderSize="8192"
       maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
       enableLookups="false" disableUploadTimeout="true"
       acceptCount="100" scheme="https" secure="true"
       clientAuth="want" sslProtocol="TLS"
       keystoreFile="/path/to/keystore.jks" keystorePass="secret"
       truststoreFile="/path/to/myTrustStore.jks" truststorePass="secret" />
<!-- if you do not specify a truststoreFile, then the default java "cacerts" truststore will be used-->

 The clientAuth="want" tells Tomcat to request that the Browser provide a User certificate if one is available. If you want to force the use of User certificates, replace "want" with "true". If you specify "want" and the browser does not have a certificate, then the Webflow configuration described below will forward the request to the userid/password form.

Note: If you specify "true" here, then Tomcat will require the Browser present a User certificate that was issued by one of the Certificate Authorities registered in the truststoreFile collection. However, the X.509 AuthenticationHandler will be configured with additional constraints. A User certificate may be acceptable to Tomcat as configured here, but fail the additional tests of the AuthenticationHandler. The Webflow will normally then send the Browser the userid/password form, since normally an interactive login is the backup when a non-interactive login fails. So if you want a URL that accepts only X.509 authentication, it is not enough to simply change "want" to "true". You also have to change the Webflow so that the Browser is never forwarded to the interactive form.

The keystore can be in JKS (a collection of keys and certificates created by Sun for Java) or PKCS12 (a collection of keys and certificates based on public standards) format when using Tomcat. When using both PKCS12 and JKS keystore types then you should specify the type of each keystore by using the keystoreType and truststoreType attributes.

The JKS (Java Key Store) file format is maintained by a tool provided by Sun in the /bin subdirectory of the Java Development Kit (JDK) distribution of your current version of Java. It is documented in http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html. Generally, you will import the certificate of the institutional Certificate Authority (the one that issues User certificates) using the command:

keytool --import -alias myAlias \
   -keystore myTrustStore.jks \
   -file certificateForInstitutionalCA.crt

Then myTrustStore.jks would become the value of the truststoreFile parameter of the Tomcat Connection configuration element.