Certificate Management Service:Install an SSL certificate on a Tomcat server (Windows)

Requirements

Step 1: Prepare the SSL certificate

1. Go to the SSL Certificate Management page. In the Actions column of the target certificate, click More to open the certificate details page. On the Download tab, download the certificate for Server Type Tomcat.

2. Extract the downloaded certificate package. It contains a certificate file (.pfx or .jks) and a password file (.txt).

   Note

   If you generated the CSR using OpenSSL or Keytool, the private key exists only on your local machine and is not included in the download. If lost, you must purchase a commercial certificate again and generate a new CSR and private key.

3. Upload the certificate and password files to a secure directory on your server. Example path: D:\cert.

   Note

   The following steps use an Alibaba Cloud ECS instance as an example. For other server types, consult their documentation.

   1. Go to ECS console - Instances. In the top-left corner, select the region and resource group for the target resource.

   2. On the instance details page, click Connect and select Workbench. Follow the on-screen instructions to log on to the server desktop.

   3. In the lower-left corner of the server desktop, click the Enabling menu. Find and open This PC, Computer, or File Explorer.

   4. Under Redirected drives and folders, double-click workbench on ***. Drag the certificate file from your local machine into this directory, and then right-click the folder and select Refresh.

      

   5. Copy the file to the D:\cert directory.

      Important

      Workbench automatically deletes all uploaded files in the Redirected drives and folders directory when you disconnect, reconnect, or sign out. Use this directory for file transfers only.

Step 2: Configure the system and network environment

1. Open port 443 in the security group.

   Important

   If your server is deployed on a cloud platform, make sure that its security group allows inbound traffic on TCP port 443. Otherwise, the service is not accessible from the internet. The following operations use an Alibaba Cloud ECS instance as an example. For other cloud platforms, see their official documentation.

   1. Go to the ECS Instances page, select the region where your target ECS instance is located, and click the instance name to go to the details page.

   2. Click Security Groups > Inbound Rules and make sure a rule exists with Action set to Allow, Protocol Type set to TCP, Port Range set to HTTPS(443), and Authorization Object set to Anywhere (0.0.0.0/0).

   3. If such a rule does not exist, add one to the target security group. For more information, see Add a security group rule.

2. Open port 443 in the server firewall.

   1. Log on to your Windows server, click the Start menu, and then open Control Panel.

   2. Go to System and Security > Windows Defender Firewall > Check firewall status.

   3. If the firewall is turned off as shown in the following figure, no further action is required.

   4. If the firewall is turned on, follow these steps to allow HTTPS traffic.

      1. In the left-side navigation pane, click Advanced settings > Inbound Rules and check whether an inbound rule exists for which Protocol is TCP, Local Port is 443, and Action is Block.

      2. If such a rule exists, right-click the rule, select Properties, and on the General tab, change the action to Allow the connection. Then, click Apply.

Step 3: Deploy the certificate on Tomcat

1. Edit server.xml to configure SSL settings. Example path: C:\apache-tomcat-9.0.105\conf\server.xml.

   PFX example

   <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
              maxThreads="150" SSLEnabled="true"
              maxParameterCount="1000">
       <SSLHostConfig>
           <!-- Replace D:/cert/example.com.pfx with the actual path to your certificate file. Replace your_certificate_password with the content of the pfx-password.txt file. -->
           <Certificate certificateKeystoreFile="D:/cert/example.com.pfx"
                        certificateKeystorePassword="your_certificate_password"
                        certificateKeystoreType="PKCS12"
                        type="RSA"/>
       </SSLHostConfig>
   </Connector>

   JKS example

   <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol"
              maxThreads="150" SSLEnabled="true"
              maxParameterCount="1000">
       <SSLHostConfig>
           <!-- Replace D:/cert/example.com.jks with the actual path to your certificate file. Replace your_certificate_password with the content of the jks-password.txt file. -->
           <Certificate certificateKeystoreFile="D:/cert/example.com.jks"
                        certificateKeystorePassword="your_certificate_password"
                        certificateKeystoreType="JKS"
                        type="RSA" />
       </SSLHostConfig>
   </Connector>

2. Optional: Configure automatic HTTP-to-HTTPS redirection.

   1. Edit server.xml. Locate the HTTP connector (default port 8080) and set the redirectPort attribute to 443. Add the attribute if it does not exist.

      <!-- Tomcat listens on port 8080 by default. Change this to the actual HTTP port that you are listening on. -->
      <Connector port="80" protocol="HTTP/1.1"
                 connectionTimeout="20000"
                 redirectPort="443"
                 maxParameterCount="1000"
                 />

   2. Add the following to the end of web.xml:

      <security-constraint>
          <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>

      Note

      After saving, the server redirects all HTTP requests to HTTPS.

3. After saving the configuration, navigate to the bin directory of your Tomcat installation and restart the server for the SSL settings to take effect.

   • Stop the Tomcat server.

     shutdown.bat

   • Start the Tomcat server.

     startup.bat

Step 4: Verify the deployment

Deploying to production

When you deploy an application in a production environment, follow these best practices to improve security, stability, and maintainability:

• Run the application as a non-administrator user:

  Create a dedicated, low-privilege system user for the application. Do not run the application by using an account that has administrative permissions.

  Note

  We recommend that you use a gateway-level SSL configuration. This involves deploying the certificate on a reverse proxy, such as an SLB or Nginx instance. The reverse proxy terminates HTTPS traffic and then forwards the decrypted HTTP traffic to the backend application.

• Externalize credential management:

  Do not hard-code sensitive information, such as passwords, in your code or configuration files. Use environment variables, a vault, or a Key Management Service provided by your cloud provider to inject credentials.

• Enforce HTTP-to-HTTPS redirection:

  Make sure that all traffic that accesses your website over HTTP is automatically redirected to HTTPS. This helps prevent man-in-the-middle (MITM) attacks.

• Configure modern TLS protocols:

  In your server configuration, disable obsolete and insecure protocols, such as SSLv3, TLS 1.0, and TLS 1.1. Enable only TLS 1.2 and TLS 1.3.

• Monitor certificates and automate renewal:

  After the certificate is deployed, we recommend that you enable domain name monitoring. Alibaba Cloud automatically checks the validity period of the certificate and sends reminders before the certificate expires. This helps you renew the certificate in a timely manner to prevent service interruptions. For more information, see Purchase and enable public domain name monitoring.

Certificate not working or HTTPS inaccessible

Common causes:

• Port 443 is blocked by the server's security group or firewall. Configure the system and network environment.

• The domain name is not included in the certificate's Bound Domains. Domain name match.

• Tomcat was not restarted after modifying the configuration. Stop and restart the Tomcat service.

• The certificate file was not replaced correctly, or the path in the Tomcat configuration is incorrect. Verify that both the configuration and certificate file are current and valid.

• The domain name is integrated with cloud services such as CDN, SLB, or WAF, but the certificate is not installed on the corresponding service. For more information, see Certificate deployment location when traffic passes through multiple cloud services.

• The domain name resolves to multiple servers, but the certificate is installed on only some of them. You must install the certificate on each server.

Update an SSL certificate in Tomcat

Back up the existing certificate files (.pfx or .jks and the .txt file) on your server. Download the new certificate files from the Certificate Management Service console and upload them to overwrite the existing files. Keep the same paths and filenames. Restart Tomcat for the new certificate to take effect.

After I restart Tomcat, the service fails to start and the log (catalina.log) shows a LifecycleException or Keystore was tampered with, or password was incorrect error.

Common causes:

• Incorrect password:

  The certificateKeystorePassword value in server.xml does not match the actual certificate password. Verify the password—it is case-sensitive.

• Incorrect certificate path:

  The path in certificateKeystoreFile is incorrect. Check for typos and consider using a path relative to the conf/ directory.

• Mismatched keystore type:

  The certificateKeystoreType does not match the actual certificate file format. Use PKCS12 for PFX files and JKS for JKS files.

• Special characters in the password:

  The password contains XML special characters such as &, <, or > that are not properly escaped in the server.xml file.

Automatic HTTP to HTTPS redirection

Follow the Set up automatic redirection from HTTP to HTTPS section. Restart Tomcat after modifying the configuration.