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

Usage notes

Step 1: Prepare the SSL certificate

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

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

   Note

   If you used a tool such as OpenSSL or Keytool to generate the Certificate Signing Request (CSR) file when you requested the certificate, the private key file is saved only on your local machine. The downloaded certificate package does not contain the private key. If the private key is lost, the certificate cannot be used. You must purchase an official certificate and generate a new CSR and private key.

3. Upload the certificate and private key files to your server and store them in a secure external directory (the example path in this topic is D:\cert).

   Note

   The following steps use an Alibaba Cloud Elastic Compute Service (ECS) instance as an example. For other types of servers, see their official documentation.

   1. Go to ECS console - Instances. In the top navigation bar, select the target region and resource group.

   2. Locate the target instance. Click Connect and select Sign in now. Log on to the server desktop as prompted.

   3. In the lower-left corner of the server, click the Start menu. Find and open This PC.

   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 uploaded file to the D:\cert directory.

      Important

      When you disconnect from or reconnect to an instance, Workbench automatically purges all uploaded files from the Redirected drives and folders directory to save space. This directory is for file transfers only. Do not save files in it.

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 access on TCP port 443. Otherwise, the service cannot be accessed from the Internet. The following steps use Alibaba Cloud ECS as an example. For other cloud platforms, see their official documentation.

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

   2. Click Security Group > All Intranet Inbound Rules, and make sure that a rule exists with the following settings: Authorization Policy is set to Allow, Protocol Type is TCP, Destination Port Range is HTTPS (443), and Authorization Object is set to Anywhere (0.0.0.0/0).

   3. If the preceding rule does not exist, see Add a security group rule to add the corresponding rule to the target security group.

2. Open port 443 in the server firewall.

   1. Log on to the Windows server, click the Start menu in the lower-left corner, and open Control Panel.

   2. Click System And Security > Windows Firewall > Check Firewall Status.

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

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

      1. In the left navigation pane, click Advanced Settings > Inbound Rules, and check for an inbound rule where the Protocol is TCP, the Local Port is 443, and the Action is Block.

      2. If such a rule exists, right-click it and select Properties. On the General tab, change the setting to Allow The Connection and click Apply.

Step 3: Deploy the certificate on the Tomcat server

1. Edit the Tomcat configuration file server.xml to modify the certificate-related settings (example path: C:\apache-tomcat-9.0.105\conf\server.xml).

   PFX format Tomcat 9.0 configuration 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. Replace your_certificate_password with the password from the pfx-password.txt file. -->
           <Certificate certificateKeystoreFile="D:/cert/example.com.pfx"
                        certificateKeystorePassword="your_certificate_password" type="RSA"/>
       </SSLHostConfig>
   </Connector>

   JKS format Tomcat 9.0 configuration 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. Replace your_certificate_password with the password from the jks-password.txt file. -->
           <Certificate certificateKeystoreFile="D:/cert/example.com.jks"
                        certificateKeystorePassword="your_certificate_password" type="RSA" />
       </SSLHostConfig>
   </Connector>

2. (Optional) Set up automatic redirection from HTTP to HTTPS.

   1. Edit the Tomcat configuration file server.xml. Find the HTTP connector (Tomcat listens on port 8080 by default) and modify the redirectPort attribute. If it does not exist, add it.

      <!-- 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 configuration at the end of the web.xml file.

      <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 you save these configurations, the server automatically redirects HTTP requests to HTTPS.

3. After saving the configurations, navigate to the bin directory of your Tomcat installation and restart the server to apply the SSL settings.

   • Stop the Tomcat server.

     shutdown.bat

   • Start the Tomcat server.

     startup.bat

Step 4: Verify the deployment

Going live

When you deploy to a production environment, follow these best practices to enhance security, stability, and maintainability:

• Run as a non-administrator user:

  Create a dedicated, low-privilege system user for the application. Never run the application with an account that has administrator privileges.

  Note

  A recommended approach is to configure SSL at the gateway layer. This involves deploying the certificate on a Server Load Balancer (SLB) or a reverse proxy such as Nginx. The gateway terminates the HTTPS traffic and forwards the decrypted HTTP traffic to the backend application.

• Externalize credential management:

  Never hard-code passwords or other sensitive information in your code or configuration files. Use environment variables, Vault, or a cloud provider's key management service to inject credentials.

• Enforce HTTP to HTTPS redirection:

  Redirect all HTTP traffic to HTTPS to prevent man-in-the-middle attacks.

• Configure modern TLS protocols:

  Disable old and insecure protocols (such as SSLv3, TLSv1.0, and TLSv1.1) in your server configuration. Enable only TLSv1.2 and TLSv1.3.

• Monitor certificates and automate renewal:

  After you deploy the certificate, enable domain monitoring. Alibaba Cloud automatically checks the certificate validity period and sends renewal reminders before expiration to help you renew in a timely manner and avoid service interruption. For detailed instructions, see Purchase and enable public domain name monitoring.

Why is my certificate not working or HTTPS inaccessible after installation or update?

This issue is often caused by one of the following configuration problems. Check them in order:

• Port 443 blocked: The server's security group or firewall does not have port 443 open. See Configure the system and network environment.

• Domain mismatch: The domain you are accessing is not listed in the certificate's Bound Domains. See Domain name match.

• The Tomcat service was not restarted after the configuration file was modified. For more information, see Stop and restart the Tomcat service.

• Incorrect certificate configuration: The certificate file was not replaced correctly, or the certificate path is not correctly specified in the Tomcat configuration. Check that the Tomcat configuration file and the certificate file are the latest and valid versions.

• Missing certificate on other services: If your domain uses services such as a Content Delivery Network (CDN), Server Load Balancer (SLB), or Web Application Firewall (WAF), the certificate must also be installed on those services. See Certificate deployment locations when traffic passes through multiple Alibaba Cloud services to complete the setup.

• Incomplete deployment on multiple servers: If your domain's DNS resolves to multiple servers, the certificate must be installed on all of them.

What is the correct procedure to update or replace an existing SSL certificate on a Tomcat server?

To replace a certificate, you must update the certificate files on the server and then restart Tomcat. Follow these steps:

1. Back up the old certificate: Before making changes, create a backup of your existing certificate files (such as the .pfx or .jks file) and the corresponding password file (.txt).

2. Replace the certificate files: Download the new certificate files from the Certificate Management Service console. Upload them to the server, overwriting the old files. Ensure the new files have the exact same name and are in the same location as the ones being replaced.

3. Restart the Tomcat service: Stop and then start the Tomcat service to load the new certificate.

How do I fix a LifecycleException or Keystore was tampered with, or password was incorrect error in Tomcat's catalina.log after configuring an SSL certificate?

This error means Tomcat cannot load your certificate keystore from the server.xml configuration. It is almost always caused by one of the following issues:

• Incorrect Password: The certificateKeystorePassword value in server.xml does not match the actual password for your keystore file. Passwords are case-sensitive.

• Incorrect File Path: The path specified in certificateKeystoreFile is wrong, and Tomcat cannot find the file. Verify the path is correct and the file exists.

• Incorrect Keystore Type: The certificateKeystoreType value does not match your certificate's file format. It should be PKCS12 for .pfx files and JKS for .jks files.

• Unescaped Special Characters: If your password contains XML special characters (such as &, <, >), they must be properly escaped (e.g., &, <, >) in the server.xml file.

How can I configure Tomcat to automatically redirect all HTTP traffic to HTTPS?

You can enforce HTTPS by modifying two configuration files: server.xml to handle the port redirection and web.xml to define a security constraint.

Follow the detailed instructions in the section: Set up automatic redirection from HTTP to HTTPS. After saving the changes, you must restart the Tomcat service for the redirect to become active.