There are many benefits to running secure production WebClient/Websydian web applications under both Tomcat and Apache. This configuration can be the highest performance option, and can be run under SSL for security. Tomcat and Apache are both open source, free software that are proven in high performance environments. While lacking some of the management features of advanced application servers like IBM Websphere, the reduced cost can make up for this in many cases.

I. How it Works

The following diagram depicts a high-level view of the architecture:

There are two major components in the setup: the Apache web server and a Tomcat servlet container.

Apache is a fully-featured web server, meaning it has the ability to serve static pages to users while offering a variety of options that provide value in web environments. Strictly a web server, it has no ability to serve dynamic pages, in other words, content that changes with user input or other sources of data. Dynamic pages might be implemented with Apache by using different mechanisms like modules to allow execution of languages like PHP and Perl. In this scenario, the mod_jk module is used to connect Apache with an existing Tomcat installation, obtaining the equivalent result of enabling Apache to serve dynamic pages but with help from an external service.

A web client is defined as a single user requesting content from a web server. The web server will handle requests and return a response for each client’s request. This is the basic interaction between clients and servers in web applications. In this setup, web clients will be able to establish a secure communications channel between them and the server by using the HTTPS (HTTP over SSL) protocol. HTTPS support is provided by mod_ssl, an extension module for the Apache Web Server.

II. Prerequisites

Windows 2003/2008 Server preinstalled

JRE (Java Runtime Environment) 5 or 6 installed

For SSL support, a SSL certificate and private key. A test certificate (self-signed) may be used for testing.

III.     Setup and Installation

1. Obtain and Install the Apache Web Server 2.2

Download the Apache web server from http://httpd.apache.org. The version to get is the one designated as “Win32 Binary including OpenSSL 0.9.8k (MSI Installer)”. Versions may vary due to new releases. The version chosen for this guide is: apache_2.2.13-win32-x86-openssl-0.9.8k.msi.

Run the installer and follow the instructions:

After a few informative dialogs you will reach the Server Information section. This dialog shows some relevant configuration information; you can accept the default values in most cases. The default port for web servers is 80. Unless you have special requirements it is recommended you leave it that way.

Select the typical installation mode:

Choose an install location:

Finally, begin the installation:

Follow the next steps:

• Stop the Apache web server service by using Window’s services manager. The service name should be “Apache2.2“. Alternatively, you may use the included Apache Service Monitor utility available in the system tray after you install Apache.
  
• Edit the httpd.conf file located at “C:\Program Files\Apache Software Foundation\Apache2.2\conf” (the base directory will vary if you used a different location while installing) with a text editor:
  
  • Search for “#LoadModule ssl_module modules/mod_ssl.so” (without quotes) and remove the
    “#” character at the beginning so the line now looks like this: “LoadModule ssl_module modules/mod_ssl.so”. This enables the loading of mod_ssl by uncommenting the line.
    
  • Search for “#Include conf/extra/httpd-ssl.conf” and remove the “#” character like in the previous step. This will enable the inclusion of mod_ssl-specific configuration.
    
  • Copy your SSL certificate and private key to the “C:\Program Files\Apache Software Foundation\Apache2.2\conf” directory. Rename the certificate and private key to “server.crt” and “server.key“.respectively. Note: the key must not be encrypted because it’s not supported under the Windows platform.

3. Enable and Configure SSL Support for Apache

1. Download the connector module for Apache from http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/win32/. The module selected for this guide is the latest version for Apache 2.2.x series: mod_jk-1.2.28-httpd-2.2.3.so.
   
2. Rename the module to mod_jk.so and place it in the “C:\Program Files\Apache Software Foundation\Apache2.2\modules” directory.
   
3. Edit the httpd.conf and add the line “LoadModule jk_module modules/mod_jk.so” after the line “#LoadModule vhost_alias_module modules/mod_vhost_alias.so” or whatever line is at the end of the LoadModule list.
   
4. Add the line “Include conf/extra/httpd-jk.conf” at the end of the httpd.conf file.
   
5. Create a text file named httpd-jk.conf at “C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra” with the following content:
   

   JkWorkersFile “C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra\workers.properties”
   

   JkLogFile “C:\Program Files\Apache Software Foundation\Apache2.2\logs\mod_jk.log”
   

   JkShmFile “C:\Program Files\Apache Software Foundation\Apache2.2\logs\mod_jk.shm”
   

   JkLogStampFormat “[%a %b %d %H:%M:%S %Y] ”
   

6. Update the directories above if you used a different base directory.
   
7. Create a text file named workers.properties at “C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra” with the following content:
   

   # Define 1 real worker using ajp13
   

   worker.list=worker1
   

   # Set properties for worker1 (ajp13)
   

   worker.worker1.type=ajp13
   

   worker.worker1.host=localhost
   

   worker.worker1.port=8009
   

8. Open the file httpd-ssl.conf at “C:\Program Files\Apache Software Foundation\Apache2.2\conf\extra” and add the line “JkMount /cdbdev/* worker1” just before the closing tag “</VirtualHost>” located at the end of the file. This will have the effect of redirecting every request from “/cdb” to the context at Tomcat with the same name. This value may vary depending on the name of the application and requirements.
   

4. Install Tomcat and Application

Download the latest release of Tomcat of the 6.0.x series. The installer version chosen for this release is 6.0.20 (file is apache-tomcat-6.0.20.exe).

Run the installer:

When you arrive at the Choose Components section select the following options:

Select the Custom install type from the combo box and enable both Service and Native options; proceed by clicking on Next.

Select an install location:

Provide a username and password for administering Tomcat. It is recommended to use port 8080 for Tomcat unless special requirements arise:

Select the location of the JRE that Tomcat will use (the default value is usually OK):

The installer will then extract the files to the location previously specified. After that, the installer will finish; close it by clicking on Finish making sure the Run Apache Tomcat option is checked:

 

 

 

  

 

 

  

Now it is time to deploy the application that users will be ultimately accessing. To do so, go to the following URL by using any web browser: http://localhost:8080/manager/html

Scroll down to the Deploy section. In the WAR file to deploy subsection click the browse button and locate the WAR file of the application to be deployed:

Click on the Deploy button. The application will start deploying; it may take several minutes depending on the size of the application.

After the process of deployment has finished you will see the new application published on its own context. From now on, you may manage the application from this interface:

4. Validate Setup

To test the install, go to the URL of the application by accessing it through Apache and SSL (HTTPS / port 443) not Tomcat, for example:

https://localhost/dev/site/websydianwebclientapp

You should see the application. Depending on the validity of the certificate, you may get a security warning; you can ignore this if the certificate used is self-signed (for testing and development)

The equivalent way to access the application in Tomcat in this case would be:

https://localhost:8080/dev/site/websydianwebclientapp

Notice the difference in port and protocol in the URL. This URL shouldn’t be accessible to outside users since it would defeat the purpose of using Apache in the first place, besides the lack of SSL security. A way of effectively controlling access is to open port 80 and port 443 to external users and block any other port including 8080.

IV. Generating a Certificate Signing Request

In order to obtain a valid certificate from a Certificate Authority like Verisign or Thawte, a Certificate Signing Request (CSR) must be generated first. Normally, certificate authorities provide instructions and guidance on generating CSRs. For convenience, instructions are provided here to create one with the Apache Web Server.

Before executing the steps needed, copy the file openssl.conf located in the conf\extras directory to the bin directory in the Apache Web Server root folder. Finally, open a command line window and go to the bin folder of the Apache Web Server root folder in order to execute the commands listed below.

Follow these steps:

1. Generate a private key
   

   Execute the following command:
   openssl genrsa –out server.key 1024 –config openssl.conf
   

This command will generate the unencrypted private key server.key.

1. Generate the CSR
   

   
   Execute the following command:
   openssl req –new –key server.key –out server.csr 
   

This command will prompt for the following X.509 attributes of the certificate:

• Country Name: Use the two-letter code without punctuation for country, for example: US or CA.
  
• State or Province: Spell out the state completely; do not abbreviate the state or province name, for example: California
  
• Locality or City: The Locality field is the city or town name, for example: Berkeley. Do not abbreviate. For example: Saint Louis, not St. Louis
  
• Company: If your company or department has an &, @, or any other symbol using the shift key in its name, you must spell out the symbol or omit it to enroll. Example: XY & Z Corporation would be XYZ Corporation or XY and Z Corporation.
  
• Organizational Unit: This field is optional; but can be used to help identify certificates registered to an organization. The Organizational Unit (OU) field is the name of the department or organization unit making the request. To skip the OU field, press Enter on your keyboard.
  
• Common Name: The Common Name is the Host + Domain Name. It looks like “www.company.com” or “company.com”.
  

VeriSign (and others) certificates can only be used on Web servers using the Common Name specified during enrollment. For example, a certificate for the domain “domain.com” will receive a warning if accessing a site named “www.domain.com” or “secure.domain.com”, because “www.domain.com” and “secure.domain.com” are different from “domain.com”.

Do not enter your email address, challenge password or an optional company name when generating the CSR.

Now you can use the generated CSR file (server.csr) in the bin directory and submit it to a Certificate Authority and obtain a valid certificate.

Backup the files generated
Backup the key and csr files to a secure location.

V. Troubleshooting

Refer to this section when encountering problems in any of the components of the setup.

Components and error conditions:

• Apache Web Server
  
  • Apache service not starting or displaying web server related errors in the web browser:
    See the end of the error log file (error.log) located in the logs directory in the root folder (most likely C:\Program Files\Apache Software Foundation\Apache2.2) of the Apache web server to determine the root cause of the problem.
    
• Tomcat Servlet Container
  
  • Tomcat service not starting or displaying container related errors in the web browser:
    See the end of the different log files Tomcat generates in the logs directory in the root folder (most likely C:\Program Files\Tomcat 6.0) of Tomcat. Various files are usually generated, so you will have to review the latest ones generated and look for any errors being reported.

VI. Additional References

• Apache Software Foundation – http://www.apache.org
• Apache HTTP Server Project – http://httpd.apache.org
• Apache Tomcat – http://tomcat.apache.org
• Apache Tomcat Connector – http://tomcat.apache.org/connectors-doc
• mod_ssl – http://www.modssl.org