Page History

...

The following sections show how to set up the most commonly-used Java Servlet containers to support HTTP over SSL.

Enabling the HTTPS support in Tomcat

...

itself (running on ports 8080 and 8443)

Loosely based on http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html.

1. For Production use: Follow this procedure to set up SSL on your server. Using a "real" server certificate ensures your users' browsers will accept it without complaints. In the examples below, $CATALINA_BASE is the directory under which your Tomcat is installed.

   1. Create a Java keystore for your server with the password changeit, and install your server certificate under the alias "tomcat". This assumes the certificate was put in the file server.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -v -storepass changeit -keystore $CATALINA_BASE/conf/keystore -alias tomcat -file myserver.pem

   2. Install the CA (Certifying Authority) certificate for the CA that granted your server cert, if necessary. This assumes the server CA certificate is in ca.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias ServerCA -file ca.pem

   3. Optional – ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the configuration section for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in client1.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1 -file client1.pem

   4. Now add another Connector tag to your server.xmlTomcat configuration file, like the example below. The parts affecting or specific to SSL are shown in bold. (You may wish to change some details such as the port, pathnames, and keystore password)

      Code Block
      language html/xml
      <Connector port="8443" URIEncoding="UTF-8"  maxThreads="150" minSpareThreads="25" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" sslProtocol="TLS" keystoreFile="conf/keystore" keystorePass="changeit"  clientAuth="true" - ONLY if using client X.509 certs for authentication! truststoreFile="conf/keystore" truststorePass="changeit" />

      Also, check that the default Connector is set up to redirect "secure" requests to the same port as your SSL connector, e.g.:

      Code Block
      language html/xml
      <Connector port="8080" maxThreads="150" minSpareThreads="25" enableLookups="false" redirectPort="8443" acceptCount="100" />

2. Quick-and-dirty Procedure for Testing: If you are just setting up a DSpace server for testing, or to experiment with HTTPS, then you don't need to get a real server certificate. You can create a "self-signed" certificate for testing; web browsers will issue warnings before accepting it, but they will function exactly the same after that as with a "real" certificate. In the examples below, $CATALINA_BASE is the directory under which your Tomcat is installed.

   1. Create a new key pair under the alias name "tomcat". When generating your key, give the Distinguished Name fields the appropriate values for your server and institution. CN should be the fully-qualified domain name of your server host. Here is an example:

      Code Block
      $JAVA_HOME/bin/keytool -genkey \ -alias tomcat \ -keyalg RSA \ -keysize 1024 \ -keystore $CATALINA_BASE/conf/keystore \ -storepass changeit \ -validity 365 \ -dname 'CN=dspace.myuni.edu, OU=MIT Libraries, O=Massachusetts Institute of Technology, L=Cambridge, S=MA, C=US'

      You should be prompted for a password to protect the private key.

      Since you now have a signed server certificate in your keystore you can, obviously, skip the next steps of installing a signed server certificate and the server CA's certificate.

   2. Optional – ONLY if you need to accept client certificates for the X.509 certificate stackable authentication module See the configuration section for instructions on enabling the X.509 authentication method. Load the keystore with the CA (certifying authority) certificates for the authorities of any clients whose certificates you wish to accept. For example, assuming the client CA certificate is in client1.pem:

      Code Block
      $JAVA_HOME/bin/keytool -import -noprompt -storepass changeit \ -trustcacerts -keystore $CATALINA_BASE/conf/keystore -alias client1 \ -file client1.pem

   3. Follow the procedure in the section above to add another Connector tag, for the HTTPS port, to your server.xml file.

Using SSL on Apache HTTPD

...

in front of Tomcat (running on ports 80 and 443)

If you choose One of the easiest routes to both running DSpace on standard ports (80 and 443) as well as using HTTPS is to install Apache HTTPD as your primary HTTP server, you can have and use it to forward requests to the Tomcat servlet container via Apache Jakarta Tomcat Connector. This can be configured to work over SSL as well. First, you must configure Apache for SSL; for Apache 2.0 see Apache SSL/TLS Encryption for information about using mod_ssl.

If you are using X.509 Client Certificates for authentication: add these configuration options to the appropriate httpd configuration file, e.g. ssl.conf, and be sure they are in force for the virtual host and namespace locations dedicated to DSpace:

##  SSLVerifyClient can be "optional" or
	"require"
        SSLVerifyClient optional
        SSLVerifyDepth  10
        SSLCACertificateFile
	path-to-your-client-CA-certificate
        SSLOptions StdEnvVars ExportCertData

Now consult the Apache Jakarta Tomcat Connector documentation to configure the mod_jk (note: NOT mod_jk2) module. Select the AJP 1.3 connector protocol. Also follow the instructions there to configure your Tomcat server to respond to AJP.

To use SSL on Apache HTTPD with mod_webapp consult the DSpace 1.3.2 documentation. Apache have deprecated the mod_webapp connector and recommend using mod_jk.

...

Tomcat.

1. Install Apache HTTPD alongside your Tomcat instance

2. In your Tomcat's server.xml, ensure that the AJP Connector is UNCOMMENTED.  Usually this runs on port 8009, but you can decide to change the port if you desire

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

3. Choose how you'd like to redirect requests from Apache HTTPD to Tomcat. There are two primary options (mod_proxy OR mod_jk), just choose ONE. (NOTE: "mod_proxy" is often the easier of the two):
   
   1. OPTION 1: Use "mod_proxy" and "mod_proxy_ajp" Apache modules to redirect requests to Tomcat (via AJP Connector) - RECOMMENDED
      
      1. Install "mod_proxy" and "mod_proxy_ajp" (usually they are installed by default with Apache HTTPD)
      2. Enable both "mod_proxy" and "mod_proxy_ajp" modules. How you do this is often based on your operating system
         
         1. In Debian / Ubuntu, there's an "a2enmod" command that enables Apache 2 modules.  So, you can just run: sudo a2enmod proxy proxy_ajp
         2. In other operating systems, you may need to find the appropriate "LoadModule" configurations (in Apache HTTPD's main config) and uncomment it. You'll then need to restart Apache HTTPD

      3. Create a new Virtual Host in Apache HTTPD to represent your DSpace site. Here's a basic example of a Virtual Host responding to any port 80 requests for "my.dspace.edu":

         Code Block

         <VirtualHost *:80> # Obviously, replace the ServerName with your DSpace site URL ServerName my.dspace.edu ## Apache HTTPD Logging Settings - modify how you see fit ErrorLog ${APACHE_LOG_DIR}/my.dspace.edu-error.log CustomLog ${APACHE_LOG_DIR}/my.dspace.edu-access.log combined # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. LogLevel warn # There are many more configurations available for Virtual Hosts, # see the documentation for more details # http://httpd.apache.org/docs/2.4/vhosts/ </VirtualHost>

      4. If you want your site to also respond to SSL requests, you'll need to install and enable "mod_ssl" and create a second Virtual Host to respond to port 443 requests. An example is provided below. But much more details are available in the Apache HTTD SSL Documentation and the mod_ssl documentation

         Code Block

         <VirtualHost *:443> # Obviously, replace the ServerName with your DSpace site URL ServerName my.dspace.edu # You can have SSL Apache logging settings here too (see the port 80 example above) # Configure your SSL Certificate (you must create one, obviously) # See the "keytool" instructions above for examples of creating this certificate # There are also many good guides on the web for generating SSL certificates for Apache SSLEngine on SSLCertificateChainFile /path/to/your/chainfile.crt SSLCertificateFile /path/to/your/public-cert.crt SSLCertificateKeyFile /path/to/your/private-key.key # More information on SSL configurations can be found in the mod_ssl documentation # http://httpd.apache.org/docs/2.4/mod/mod_ssl.html </VirtualHost>

         Info
         title Extra SSL Configurations for X.509 Client Certificates authentication
         If you are using X.509 Client Certificates for authentication: add these configuration options to the appropriate httpd configuration file, e.g. ssl.conf, and be sure they are in force for the virtual host and namespace locations dedicated to DSpace:   ## SSLVerifyClient can be "optional" or "require" SSLVerifyClient optional SSLVerifyDepth 10 SSLCACertificateFile /path/to/your/client-CA-certificate SSLOptions StdEnvVars ExportCertData

      5. In each of your Apache HTTPD Virtual Hosts (see above), use "ProxyPass" configurations to configure the redirects from Apache HTTPD to Apache Tomcat. The exact configurations depend on whether you want to redirect ALL requests to Tomcat, or just certain paths. Here's a basic example. But much more information and examples can be found in the mod_proxy documentation

         Code Block

         # These are just examples. THEY LIKELY WILL NEED MODIFICATION. # Again, remember to add these to your EXISTING <VirtualHost> settings <VirtualHost> ... (existing settings) ... # If there's a single path you do NOT want redirected, you can use ! to ignore it # In this case any requests to "/ignored_path" will be handled by Apache HTTPD and NOT forwarded to Tomcat ProxyPass /ignored_path ! # These configurations say: By default, redirect ALL requests to port 8009 # (The port MUST match the port of your Tomcat AJP Connector. By default this usually is 8009) ProxyPass / ajp://localhost:8009/ ProxyPassReverse / ajp://localhost:8009/ # You may also wish to provide additional "mod_proxy" configurations, # for more examples and details see the documentation at # http://httpd.apache.org/docs/2.4/mod/mod_proxy.html </VirtualHost>

   2. OPTION 2: Alternatively, use "mod_jk" Apache module to redirect requests to Tomcat (via AJP Connector).  For information on configuring mod_jk, please see the Apache Tomcat Connector documentation (specifically the "How To" on using the Tomcat Connector with Apache HTTPD). You may also refer to our wiki guide for installing DSpace with ModJk.
4. Finally, restart your Apache HTTPD webserver and test things out.
   1. If you hit any issues, it is recommended to search around for guides to running Apache HTTPD and Apache Tomcat using either "mod_proxy" or "mod_jk".  DSpace does not require any unique configurations with regards to this redirection from Apache to Tomcat. So, any guides that generally explain how to redirect requests from Apache to Tomcat should also work for DSpace.

The Handle Server

First a few facts to clear up some common misconceptions:

...