Tomcat proxified by Apache

Notes on how to set up Tomcat with an Apache proxy in front of it – useful for adding SSL or serving other content via Apache on the same port – written up because a *lot* of the online howtos out there are either out of date or generally unhelpful. This is a quick-and-dirty setup and works well enough for a small server with not much traffic; it’s probably not the best for a larger-scale site.

Ingredients:

  • Tomcat 7.0
  • OpenJDK Runtime Environment 1.7 (aka, Java 7)
  • Apache 2.2
  • Debian Wheezy (Linux)

Assumptions:

Already functioning LAMP server .. there are stacks of good howtos out there for getting Apache up and running, so I won’t rehash it here.

Recipe:

JRE/Tomcat Install and Config

sudo aptitude install openjdk-7-jre
sudo aptitude install tomcat7 tomcat-common tomcat-admin

Once Tomcat is installed and any dependencies are satisfied, modify /etc/tomcat7/tomcat-users.xml to allow access to the Manager webapp – add the following to the bottom of the file before </tomcat-users> (obviously substituting admin and password with something a little more creative..):

<user username="admin" password="password" roles="manager-gui,admin-gui"/>

Save and then restart Tomcat:

sudo service tomcat7 restart

Add a rule in to the firewall to allow access to port 8080, then try to load http://server.name.here:8080 – the default Tomcat page (It works !) should appear – navigate to the Manager webapp link and log in with the user/pass configured earlier in tomcat-users.xml.

At this point, it would be helpful to deploy and test a Java webapp (in a .war file) using the Manager webapp if you have one handy..

If everything works up to this point, enable the AJP connector for Tomcat – in /etc/tomcat7/server.xml, find and remove the following highlighted lines:

    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <!--
    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
    -->

Save and then restart Tomcat:

sudo service tomcat7 restart

Apache Proxy Config

Enable the proxy and proxy_ajp modules:

sudo a2enmod proxy proxy_ajp

Configure the Apache proxy for the deployed webapp in an already-functioning VirtualHost – this can be done a number of ways, but easiest inside a Location declaration (the ProxyPassReverse line should reference http:// or https:// as appropriate):

  <Location /WebappName>
    ProxyPass ajp://server.name.here:8009/WebappName
    ProxyPassReverse https://server.name.here/WebappName
  </Location>

Restart Apache:

sudo service apache2 restart

The deployed webapp should now be available at http(s)://server.name.here/WebappName.

Client Authentication for Apache 2

There are two ways to set up client authentication – the “correct” way (where you have all of your secured content in its own virtual host) and the “useful” way (where you want to have your secured content in a directory rather than the entire site).

The “useful” way involves renegotiating the SSL connection when accessing the secured content (i.e., the connection is negotiated once when you request https://www.example.com/ and then renegotiated when you request https://www.example.com/client-auth-required/). This was all fine and well, but an OpenSSL vulnerability was discovered where renegotiation handshakes were not properly associated with the existing connection – thus potentially allowing for a Man-in-the-Middle attack.

OpenSSL 0.9.8m was released to fix the bug – the fix was to switch to a newer and more poorly supported method of allowing renegotiations. Practical outcome: client authentication in many web apps using Apache and mod_ssl simply stopped working.

Sometimes you need client authentication at a directory level, and chances are you want to make it work with commonly used web browsers (i.e., Internet Explorer). Here’s how you do it:

The method of configuring client authentication as described below intentionally turns back on a known security vulnerability in Apache. For obvious reasons, this isn’t recommended. If you can, set up your secured content in its own virtual host (the “correct” way).

This recipe makes use of the following ingredients:

  • Apache 2.2.15 or newer
  • OpenSSL (mod_ssl) 0.9.8m or newer

If you haven’t got the above two items, you need to fix that first.

Assumption: you’ve already got SSL set up and working – there are at least 9000 howto’s on the Internets, so little point in covering that here.

Once you have SSL working without error, you’ll need to add this to your VirtualHost configuration:

SSLVerifyClient require
SSLVerifyDepth x
SSLCACertificateFile /path/to/client-cert-issuing-chain.crt
SSLCADNRequestFile /path/to/client-cert-issuing-ca.crt
SSLInsecureRenegotiation on

The first line requires a certificate from the client.

The second line tells the server how far down it can traverse a chain to verify a certificate before giving up – 1 if the certificate is directly signed by a Root CA, 2 if there’s one Intermediate CA and so on.

The third line tells the server what CAs to trust for client authentication; if you have a chained hierarchy for issuing client certificates, this file should contain all of the Intermediate CAs up to and including the Root CA (concatenated together in PEM format). Not sure what version of Apache started requiring the full chain, but you’ll get non-obvious errors in your log files if you don’t have all of the CAs required here.

The fourth line tells the client what CAs the server will accept a certificate for, and should point to a file containing the Issuing CA (in PEM format) for your client certificates. This command is particularly important if you use an Intermediate CA to issue client certificates. It’s optional – and doesn’t get used to actually validate client certificates – but Internet Explorer pays attention to this statement when working out a list of acceptable client certificates for the user to pick from, so it’s not such a bad idea to include it.

The fifth line does exactly what it says; it’s what actually makes client authentication work at a directory level. Do note that the fifth line is only valid within a Server or Virtual Host context; you can’t use it in a Directory or Location section.

You will then need the following at the Directory level:

SSLRequireSSL
<FilesMatch “.(cgi|pl)$”>
SSLOptions +StdEnvVars
</FilesMatch>

Obviously this is in addition to whatever else you have configured for the Directory section.

The first line requires a SSL’ed connection.

The FilesMatch section and SSLOptions statement aren’t absolutely required, but if you want to log any of the information from the client certificate the user is presenting, or make said information available in the environment variables – you’ll need it. Grabbing all this information comes at a performance penalty, so it makes good sense to restrict what types of files the server extracts it for.

Another item worth researching and including in your config is the SSLRequire directive – it’s reasonably complicated, but allows you to control what client certificates are allowed based on things like Subject DN and Issuer DN.

One last thing: make a point of reading the mod_ssl documentation. You’ll be glad you did!