How to setup a secure OMII Server using SSL

Introduction

This topic describes the steps involved in setting up an OMII Server for SSL (Secure Sockets Layer) communication. The motivation for doing so is to obtain message encryption for the OMII installation on the transport level. In addition, setting up an OMII server to use SSL enables clients to authenticate the server that they are trying to connect to.

For a basic guide to SSL, please see "What is SSL?" in the Reference section of the OMII User Guide.

The steps you will need to carry out are:

  1. Configure OMII Server for SSL communication.
    1. Modify the Tomcat configuration file.
    2. Test your HTTPS server.
    3. Secure the Integrated Services through SSL.  
  2. Modify the OMII Client to use SSL.
    1. Modify the Axis Test Service client.
    2. Run jobs on the Integrated Services secured through SSL.

Assumptions

It is assumed that you have installed the following and they are working correctly.

Step 1: Configure OMII Server for SSL communication.

Step 1a: Modify the Tomcat configuration file

To configure Tomcat to use SSL, we need to modify server.xml (located in the <OMII_BASE_HOME>/jakarta-tomcat-5.0.25/conf directory). Suppose we want to use port 18443 for our SSL communication. Locate the following code snippet in server.xml:

      <!-- Define an OMII-style SSL Coyote HTTP/1.1 Connector on port 18443 -->

      <!--

      <Connector port="18443"

                 maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

                 enableLookups="false" disableUploadTimeout="true"

                 acceptCount="100" debug="0" scheme="https" secure="true"

                 clientAuth="false" sslProtocol="SSL"

                 sSLImplementation="uk.ac.uk.omii.ssl.OMIIImplementation" />

      -->

This Connector should be uncommented (without change).

Note that clientAuth is set to be false. This means that the client will authenticate the server to which it is connecting but not vice-versa. The reason for this is because an OMII Server is not only used in conjunction with an OMII Client, but it is also visited by the users' browser at times. If clientAuth is set to be true, this will require a user's browser to have a valid certificate that is signed by the same CA as the server certificate; hence, for simplicity, it was decided not to enable clientAuth in this example.

Make sure you comment out the configuration for the HTTP communication. To do so, locate the following code snippet in server.xml:

      <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 18080 -->

      <Connector port="18080"

                 maxThreads="150" minSpareThreads="25" maxSpareTh reads="75"

                 enableLookups="false" redirectPort="8443" accept Count="100"

                 debug="0" connectionTimeout="20000"

                 disableUploadTimeout="true" />

Comment out the above code like this:

      <!-- Define a non-SSL Coyote HTTP/1.1 Connector on port 18080 -->

      <!-- <Connector port="18080"

                      maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

                      enableLookups="false" redirectPort="8443" acceptCount="100"

                      debug="0" connectionTimeout="20000"

                      disableUploadTimeout="true" />

      -->

Now you need to edit the file <OMII_BASE_HOME>/records/omii.  Locate the definitions of the two properties tomcat.protocol and tomcat.port.  Change the value of the former to "https", and the value of the latter to the port number you selected above (e.g. 18443).

Step 1b: Test your HTTPS server

At this point, you should restart the OMII Server. To do so, go to the  <OMII_HOME>/bin directory and type

    # ./stopomii.sh

Once shutdown is complete, restart the WS container by typing

    # ./startomii.sh

After the OMII Server has started successfully, you can use a web browser to test that it is working. Test the SSL setting by opening your browser and typing in the following URL:

     https://yourservername:18443

Note that yourservername should be replaced with the name of the machine where you installed the OMII Server. If SSL is working then you should see the default homepage for your Tomcat. Your browser may generate a warning about SSL communication before this (just click OK).

Please click here to find out how to modify your OMII Client to use SSL.

Step 1c: Secure the Integrated Services through SSL

If you have installed the Integrated Services, they should be configured to use SSL as described below.  

Visit https://localhost:18443/axis and log in as OMII administrator (default user omii, password admin).

Assuming you have already set up Tomcat to use HTTPS, you will get a message similar to:

  "Failed to connect to SOAP endpoint http://<yourservername>:18080/axis/services/JobService"

Ignore this message and follow the link Reconfigure Services - the rightmost link at the bottom of the administration page.

Change the value of the field Service provider services location to e.g  https://<yourservername>:18443/axis/services

Change the value of the field Account service provider location to e.g https://<yourservername>:18443/account/services

You will also need to re-enter the value of the Password field for the services database; the default value for this is omii.

Hit submit. You will then be prompted to restart the OMII container which MUST be done in order for the configuration changes to take effect:

Visit https://<yourservername>:18443/account/

You should see the message:

  “Failed to connect to SOAP endpoint http://<yourservername>:18080/account/services/AccountService.”

Click on Endpoints configuration.

Change the value of the field Service provider services location to e.g. https://<yourservername>:18443/account/services

Related Topics