Posted Nov 23 by Edmund Clayton.
Updated Nov 23.

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

Last activity Nov 23 by Edmund Clayton.
213 views. 0 comments.

Chapter 3 – Configuring the AppWorks Gateway for HTTPS

OpenText 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. The steps are as follows:

  1. Create a Java keystore file.
  2. Create a Certificate Signing Request (CSR).
  3. Sign the CSR File using Active Directory Certificate Services
  4. Add the Root CA Certificate to the AppWorks Gateway Server
  5. Add the Keystore to the AppWorks Gateway.

Important: In this procedure we are using Active Directory Certificate Services (ADCS). ADCS allows you to build, in-house, a public key infrastructure, with public key cryptography, digital certificates, and digital signature capabilities, using Microsoft technology. There are many alternative services that you can use, and which may be more appropriate for your organization. The use of ADCS here is for the purpose of providing an “end-to-end” example to explain the
procedures for enabling the AppWorks Gateway for HTTPS. There is no requirement to use ADCS. The implementation and maintenance of security protocols at your organization can be complex and should only be attempted by experienced personnel.

3.1 – Creating the Java Keystore File

To create a Java keystore file:

You can use the Java keytool.exe command line utility to complete these steps. However, to present the required changes as clearly as possible, we are using KeyStore Explorer. KeyStore Explore is an open source utility that provides a graphical user interface for the keytool key and certificate management functionality. KeyStore Explorer is available from http://keystore-explorer.org.

  1. Start KeyStore Explorer, click File > New and select JKS for the keystore type.

    enter image description here

  2. Click OK.

  3. Click Tools > Generate Key Pair, and select RSA for the encryption algorithm.

    enter image description here

  4. Click OK.

  5. In the Generate Key Pair Certificate dialog box, select the required Validity Period.

  6. Click Add Extensions.

  7. Click to display the Add Extension Type dialog box.

    a. Select Subject Alternative Name.

    b. Select the Critical Extension check box.

    enter image description here

  8. Click OK.

  9. In the Subject Alternative Name Extension dialog box, click and do the following:

    a. For General Name Type, select DNS Name.

    b. In the General Name Value field, enter the fully-qualified domain name of the server that you want to deploy.

    c. Click OK until the Generate Key Pair Certificate dialog box is redisplayed.

  10. Click the Edit Name button and complete the Name dialog box with details relevant to your Active Directory Certificate Server.

  11. Click OK until you are prompted for an alias name. You can leave the alias name unchanged and click OK.

  12. In the New Key Pair Entry Password dialog box, type a password.

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.

To generate a Certificate Signing Request (CSR):

  1. Right-click on the generated key pair, and select Generate CSR to create a
    certificate signing request file

  2. In the Generate CSR dialog box, select the Add certificate extensions to
    request
    check box.

    enter image description here

  3. Click Browse and choose a name and location for the CSR file and click Save.

The next step is to sign the CSR that you have created, and this guide describes how to do this using Active Directory Certificate Services. This process can be used if you are building an internal system and do not have access to an external CA, such as VeriSign. If you submit the CSR to an external CA, you should receive both the signed certificate for your server and also the root CA certificate from the Certificate Authority that was used to sign the new certificate. If the CA uses intermediate chain certificates, you will also need these.

Important: 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.

To sign the CSR file using ADCS:

Note: These steps offer a worked example using Active Directory Certificate Services. Your organization may use a third-party Certificate Authority to return a signed certificate file.

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

  2. On your ADCS server, open a web browser and navigate to https://<domain_name>/certsrv/certrqxt.asp. The Submit a Certificate Request or Renewal Request page is displayed.

  3. Copy and paste the contents of the CSR file from your text editor into the Saved Request box for Base-64–encoded certificate request (CMC or PKCS #10 file or PKCS #7).

  4. Click Submit.

  5. In the Certificate Issued page, click Download certificate chain and save the
    file to your hard disk.

  6. Return to KeyStore Explorer, right-click on the generated key pair and select
    Import CA Reply > From File.

  7. Browse to the downloaded certificate.

  8. Save the keystore as a JKS file.

To add the Root CA Certificate to the AppWorks Gateway Server

In this step, you update the Java certificate store for the Apache Tomcat instance that
is hosting the AppWorks Gateway.

  1. On the ADCS server, open a web browser and go to https://<domain_name>/certsrv/certrqxt.asp. The Download a CA Certificate, Certificate Chain, or CRL page is displayed.

  2. Click the Download CA certificate chain link.

  3. On the AppWorks Gateway server, navigate to the cacerts file in the <Java_Home>\lib\security folder.

  4. Open the cacerts file in KeyStore Explorer. The default password for the cacerts file is “changeit”.

  5. Select Tools > Import Trusted Certificate.

  6. Navigate to your downloaded CA certificate chain.

  7. Save the cacerts file.

  8. Copy the cacerts file back into the <Java_Home>\lib\security folder on the AppWorks Gateway server.

To add the new keystore to 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.

  1. Stop the Apache Tomcat server.

  2. Place your generated JKS file in the <Tomcat_Home>\conf folder on the AppWorks Gateway server.

  3. In the <Tomcat_Home>\conf directory, open the server.xml file in a text editor.

  4. Locate the <Connector element with port=“<8443>“.

  5. Uncomment the property and add the name of the JKS keystore file, and the password you provided when you created it:

    keystoreFile="/conf/keystore.jks" keystorePass="opentext123!"

    The following is the section with the additional line:

    <!-- Define a SSL/TLS HTTP/1.1 Connector on port 8443
    This connector uses the NIO implementation that requires the
    JSSE style configuration. When using the APR/native
    implementation, the OpenSSL style configuration is required as
    described in the APR/native documentation -->
    <!--
    <Connector port="<8443>"
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
    keystoreFile="/conf/keystore.jks" keystorePass="opentext123!"
    clientAuth="false" sslProtocol="TLS" />
    -->
    
  6. Save and close the file, and then restart the Apache Tomcat server.

  7. To check the setting, in a browser, type https://*<Tomcat_Host>:<8443>*

Top of page


Table of Contents

Your comment

To leave a comment, please sign in.