Installing a Certificate on Tomcat Servers

Last updated: 2020-06-04 19:32:10

    Scenarios

    This document describes how to install an SSL certificate on a Tomcat server.

    • The certificate www.domain.com is used as an example.
    • Tomcat 7.0.94 is used as an example.
    • The current server OS is CentOS 7. The detailed steps vary slightly with the OS version.

    Prerequisites

    • A remote file copy tool such as WinSCP has been installed. You are recommended to download the latest version from the official website.
    • A remote login tool such as PuTTY or Xshell has been installed. You are recommended to download the latest version from the official website.
    • The Tomcat server has been installed and configured on the current server.
    • Before you install the SSL certificate, you must have the following information.
      Name Description
      Server IP address IP address of the server, which is used to connect the PC to the server.
      Username The username used to log in to the server.
      Password The password used to log in to the server.
    • If your server is a Tencent Cloud CVM instance, you can log in to CVM console to obtain the IP address, username, and password of the server.
    • If you selected the Paste CSR method when applying for the SSL certificate, the option to download the Tomcat certificate file is not provided. Instead, you manually convert the format to generate a keystore. The procedures are as follows.
      • Access the conversion tool.
      • Upload the certificate and private key files in the Nginx folder to the conversion tool, enter the keystore password, click Submit, and convert the certificate to a JKS certificate.
    • Currently, the Tomcat server is installed in the /usr directory. For example, if the Tomcat folder name is tomcat7.0.94, then /usr/*/conf is actually /usr/tomcat7.0.94/conf.

    Directions

    Certificate Installation

    1. On the Certificate Management page of the SSL Certificate Service console, download the www.domain.com certificate and decompress it to a local directory.
      You have obtained the certificate files, including the Tomcat file folder and CSR file:
      • Folder name: Tomcat
      • Folder content:
        • www.domain.com.jks: keystore file
        • keystorePass.txt: password file (If you have already set a private key password, there is no keystorePass.txt file in this folder.)
      • CSR file: www.domain.com.csr file

        The CSR file is uploaded by you or generated by the system when you apply for the certificate and is provided to the CA. It is irrelevant to the installation.

    2. Log in to the Tomcat server using WinSCP (a tool for copying files between a local computer and a remote computer).
    3. Copy the obtained www.domain.com.jks keystore file from the local directory to the /usr/*/conf directory.
    4. Remotely log in to the Tomcat server. For example, you can use PuTTY for remote login.
    5. Edit the server.xml file in the /usr/*/conf directory by adding the following:
      <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true"
      maxThreads="150" scheme="https" secure="true"
      #Enter the path where the certificate is saved
      keystoreFile="/usr/*/conf/www.domain.com.jks" 
      #Enter the keystore password
      keystorePass="******"
      clientAuth="false"/>
      For details of the server.xml file, see the following:

      To prevent format errors, it is not recommended to copy the content of server.xml file.

      <?xml version="1.0" encoding="UTF-8"?>
      <Server port="8005" shutdown="SHUTDOWN">
       <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
       <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
       <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
       <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
       <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />
      <GlobalNamingResources>
       <Resource name="UserDatabase" auth="Container"
                 type="org.apache.catalina.UserDatabase"
                 description="User database that can be updated and saved"
                 factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
                 pathname="conf/tomcat-users.xml" />
      </GlobalNamingResources>
      <Service name="Catalina">
           <Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000"  redirectPort="8443" />
           <Connector port="443" protocol="HTTP/1.1"
                  maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
                  clientAuth="false"
                   keystoreFile="/usr/*/conf/www.domain.com.jks"
                   keystorePass="******" />
       <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />
      <Engine name="Catalina" defaultHost="www.domain.com">
         <Realm className="org.apache.catalina.realm.LockOutRealm">
           <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
                  resourceName="UserDatabase"/>
         </Realm>
       <Host name="www.domain.com"  appBase="webapps" 
           unpackWARs="true" autoDeploy="true" >
           <Context path="" docBase ="Knews" />
       <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
              prefix="localhost_access_log" suffix=".txt"  
              pattern="%h %l %u %t "%r" %s %b" />
         </Host>
       </Engine>
      </Service>
      </Server>
      The main parameters of the configuration file are the following.
      • keystoreFile: where the keystore file is saved. You can specify an absolute path or a relative path to the (Tomcat installation directory) environment variable. If this parameter is not set, by default, Tomcat reads the file named ".keystore" from the user directory of the current operating system user.
      • keystorePass: keystore password. If you set a private key password when applying for the certificate, enter the private key password; otherwise, enter the password in the keystorePass.txt file in the Tomcat folder.
      • clientAuth: if it is set to true, Tomcat requires all SSL clients to provide a security certificate for identity verification.
    6. Confirm whether the Tomcat server is started.
      • If the Tomcat server is already started, you need to run the following commands in sequence in the /usr/*/bin directory to shut down and restart it.
        ./shutdown.sh  (Shut down the Tomcat server)
        ./startup.sh (Start the Tomcat server)
      • If the Tomcat server is not started, you need to run the following command in the /usr/*/bin directory to start it.
        ./startup.sh
    7. After it is started successfully, it can be accessed using https://www.domain.com.

    Security Configuration for Automatic Redirect from HTTP to HTTPS (Optional)

    If you do not know how to configure website access over HTTPS, you can configure the server to make it automatically redirect HTTP requests to HTTPS through the following steps:

    1. Edit the web.xml file in the /usr/*/conf directory and find the </welcome-file-list> tag.
    2. Insert a new line below </welcome-file-list> and add the following:
      <login-config>
       <!-- Authorization setting for SSL -->
       <auth-method>CLIENT-CERT</auth-method>
       <realm-name>Client Cert Users-only Area</realm-name>
       </login-config>
       <security-constraint>
       <!-- Authorization setting for SSL -->
       <web-resource-collection>
       <web-resource-name>SSL</web-resource-name>
       <url-pattern>/*</url-pattern>
       </web-resource-collection>
       <user-data-constraint>
       <transport-guarantee>CONFIDENTIAL</transport-guarantee>
       </user-data-constraint>
       </security-constraint>
    3. Edit the server.xml file in the /usr/*/conf directory and modify the redirectPort parameter to port 443, the port of the SSL connector, as shown below:
      <Connector port="80" protocol="HTTP/1.1"
      connectionTimeout="20000"
      redirectPort="443" />

      This modification redirects a non-SSL connector to an SSL connector.

    4. Shut down the Tomcat server by running the following command in the /usr/*/bin directory.
      ./shutdown.sh
    5. Run the following command to confirm whether there is a problem with the configuration.
      ./configtest.sh
      • If yes, reconfigure or fix the problem as prompted.
      • If no, proceed to the next step.
    6. Run the following command to start the Tomcat server and then it can be accessed using http://www.domain.com.
      ./startup.sh

    If you encounter problems during this process, please contact us.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help