Posted Jun 08 by Edmund Clayton.
Updated Nov 30.

Learn how to configure SSL on Apache Tomcat to allow AppWorks Gateway to work with HTTPS

Last activity Nov 30 by Edmund Clayton.
1090 views. 2 comments.

Chapter 3 – SSL on Apache Tomcat

OpenText strongly recommends using SSL to increase the security of the system.
This section explains how to configure SSL on Apache Tomcat to allow the AppWorks Gateway to work with the HTTPS protocol.

3.1 – Creating the Java Keystore File

To create the Java keystore file:

  1. On the local file system, create a folder in which you will create the keystore. For example C:\new-keystore. If you do not do this, the keytool utility will create the keystore in the home directory of the user running the tool.

  2. Open a Command Prompt window and always keep the window open because it will be used throughout this chapter.

  3. Navigate to the <Java_Home>/bin directory where you will find the keytool.exe utility.

  4. Run the following command:

    keytool.exe -genkey -alias tomcat -keyalg RSA -keystore C:\newkeystore\keystore.jks

    • The name of the -alias is not important and does not have to be tomcat. You just have to make sure any aliases you create in this keystore are unique.

    • The name of the -keystore is also not important and does not have to be keystore.jks.

    The keytool.exe utility will prompt you to provide information about the keystore. Set the first and last name to the fully qualified name of the server that you want to deploy. The format should be otag.company.net.

  5. Enter all the other requested parameters. When completed, the command prompt returns.

You now have a functioning keystore for your required host. Next, you need to generate a Certificate Signing Request (CSR) that you can submit to your Certificate Authority (CA) for signing.

3.2 – Creating a Certificate Signing Request (CSR)

To create a Certificate Signing Request (CSR):

  • In the Command Prompt window you used in the previous section, run the following command:

    keytool.exe -certreq -keyalg RSA -alias tomcat -file C:\newkeystore\certreq.csr -keystore C:\new-keystore\keystore.jks

    The keytool will prompt you for the keystore password that you set when creating the keystore in the previous section.

    When complete, you should have a CSR file called certreq.csr in the keystore location on the file system.

This CSR file now needs to be submitted to your signing authority for signing. When signed, you should receive both the signed certificate for your server and also the ROOT certificate from the Certificate Authority (CA) that was used to sign the new certificate. If the CA uses intermediate chain certificates, you will also need these.

Caution: It is crucial that you have the full chain of certificates used to sign your new certificate. Without the complete chain, SSL communication will fail.

3.3 - Signing a CSR File Using Windows Certificate Services

If you have access to a local Windows Certificate Services system, you can use this to sign the CSR file that you created in the previous section. This process can be used if you are building an internal system and do not have access to an external CA, such as VeriSign.

To sign a CSR file using Windows Certificate Services:

  1. In a text editor, open the certreq.csr file that you created in the previous section.

  2. Navigate to the browser interface of the Windows Certificate Services Server.
    For example, https://domain_name/certsrv/.

  3. Click the Request a certificate link.

  4. Click the advanced certificate request link.

  5. Click the second link for base-64 encoding. For example, the Submit a certificate request by using a base-64–encoded CMC or PKCS #10 file link.

  6. Copy and paste the entire contents of the CSR file from your text editor into the Saved Request box.

  7. In the Certificate Template list, click Subordinate Certification Authority.

  8. Click Submit. You will then get an option to download the newly signed certificate in DER format.

  9. Download the certificate to a suitable location on your file system and open it.
    You now have your signed certificate. Next, you need to export the ROOT certificate used to sign it.

  10. In the certificate dialog box, click the Certification Path tab. You will see the chain of certificates.

  11. Select the root certificate and click View Certificate. The root certificate opens.

  12. For the root certificate, click the Details tab.

  13. Choose the Copy to File option. This will launch the Export Certificate Wizard.

  14. Export the certificate in DER format to the same location where you saved the server certificate.

You should now have the following:

  • A created keystore for your server.

  • A server certificate signed by your CA.

  • The root certificate from the CA that was used to sign your certificate.

3.4 - Importing the Certificate Chain into the Keystore

You now need to add your certificate chain into your keystore. This must be done in a specific order to ensure the SSL chain is correct.

To import the root signing certificate into the keystore:

  1. In the same Command Prompt window that you used in the previous sections, run the following command:

    keytool.exe -import -alias rootCA -keystore C:\new-keystore\keystore.jks -trustcacerts -file C:\new-keystore\rootca.cer

    Note: You will need to enter the keystore password.

    In this example, the root certificate used to sign the server certificate is named
    rootCA.cer.

    The —alias rootCA is a unique alias in the keystore.

    The location of the keystore is C:\new-keystore\keystore.jks.

  2. The keytool will ask if you want to import the certificate. Choose Yes.

Now that you have the root certificate in the keystore, you can add the signed server certificate.

To import the signed server certificate into the keystore:

  • In the same Command Prompt window that you used in the previous sections, run the following command:

    keytool.exe -import -alias tomcat -keystore C:\new-keystore\keystore.jks -file C:\new-keystore\newcert.cer

    Note: You will need to enter the keystore password.

    In this example, the name of the server certificate signed by the CA is
    newcert.cer.

    The -alias tomcat is the same alias in the keystore used to create the CSR.

    The location of the keystore is C:\new-keystore\keystore.jks.

You will now have a new keystore that contains the signed server certificate and the chain of certificates used to sign it. You can check the contents of the keystore using the keytool utility. For example,

keytool.exe -list C:\new-keystore\keystore.jks

This will list the certificates in your keystore.

3.5 - Adding the Keystore to the AppWorks Gateway

The Apache Tomcat instance that will host the AppWorks Gateway needs to be configured to use the chain of certificates from the new keystore so that the runtimes can communicate using SSL to the AppWorks Gateway.

By following these steps, your Apache Tomcat server can still run in normal mode at the same time on port 8080 with HTTP.

To add the new keystore to AppWorks Gateway:

  1. Stop the Apache Tomcat server.

  2. Open the server.xml file located in the <Tomcat_Home>\conf directory in a text editor.

  3. Locate the element with port=“<8443>” as seen below.

    <Connector port="<8443>"
    maxThreads="150" minSpareThreads="25" SSLEnabled="true" maxSpareThreads="75"
    enableLookups="true" disableUploadTimeout="true"acceptCount="100"debug="0"
    scheme="https"secure="true" clientAuth="false" sslProtocol="TLS"/>

  4. Ensure the line is uncommented and add the following:

    keystoreFile="C:\new-keystore\keystore.jks"keystorePass="<keystore_password>"

    The completed element is as follows:

    <Connector port="<8443>"
    maxThreads="150" minSpareThreads="25" SSLEnabled="true" maxSpareThreads="75"
    enableLookups="true" disableUploadTimeout="true"acceptCount="100"debug="0"
    scheme="https"secure="true" clientAuth="false" sslProtocol="TLS"
    keystoreFile="C:\new-keystore\keystore.jks"keystorePass="<keystore_password>"/>

  5. Save and close the file, and then restart the Apache Tomcat server.

  6. Check the setting by entering the following URL in your Web browser:

    https://*<Tomcat_Host>:<8443>*

Top of page

2 Comments

0

The Connector element needs SSLEnabled="true" otherwise it won't be listening on https. Tomcat will log an exception "Invalid character found in method name. HTTP method names must be tokens".


0

This article has been updated to include SSLEnabled="true" in the server.xml example. The same updates are available in the PDF version of the AppWorks Gateway Installation and Administration Guide, labelled as version 2, and available from the Getting Started page, the Software Downloads page, and from the Release Notes for 16.2.1 page.


Table of Contents

Your comment

To leave a comment, please sign in.