HTTPS Access by Configuring the SSL Certificate in Tomcat

This document is a third-party solution or a non-product-related operation guide, which is only for users with independent development capabilities. 

To use the HTTPS protocol, you need a valid SSL certificate, which contains identity authentication information for communication encryption.

In a single sign-on authentication system, a certificate, as an important key, secures the interaction between the client and the server.

This document only introduces how to install an SSL certificate for Tomcat in the CentOS system, helping you to access services through HTTPS. For installing an SSL certificate in other environments, you are advised to consult your certificate issuing authorities.

Certificate Obtaining

You need to first apply for a certificate before configuring it.

You need to purchase a certificate (usually authenticated by internationally recognized certificate authorities (CAs) such as VeriSign and GlobalSign) from a CA vendor by yourself.

Note:

Do not use keytool embedded in JDK to generate a certificate in formal environments. If use this tool, security warnings will be triggered and the project cannot be accessed after being embedded into a third-party platform.

Certificate Upload

1. Go to the Tomcat installation directory as the admin and create a folder named cert.

2. Go to the %Tomcat_HOME%/cert path as the admin and upload the obtained certificate to the cert folder.

Note:

1. Certificate formats may vary with vendors. You do not need to make your certificate format identical to that in the following figure.

2. A key file (if any) also needs to be uploaded to the folder.

server.xml File Configuration

1. Go to the %TOMCAT_HOME%/conf path as the admin and open the server.xml file through a text editor.

2. In the server.xml file, locate the following configuration block.

<Connector port="8080" protocol="HTTP/1.1"
            connectionTimeout="20000"
            redirectPort="8443" />

Add the following configuration block above the just mentioned configuration block. You need to modify the values of keystoreFile, keystoreType, and keystorePass based on your certificate address, format, and password.

• keystoreFile allows you to enter an absolute path or a relative path in Tomcat.

• Connector port is the port occupied during your subsequent access. Ensure that the port firewall is open and accessible. If you want to directly access services through the domain name without adding a port number, you can use the default port number 443 of HTTPS.

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
            maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
            keystoreFile="/path/to/your/keystore/file"
            keystoreType="your_keystore_type"
            keystorePass="your_keystore_password"
            clientAuth="false" sslProtocol="TLS" />

Note:

1. You are not advised to directly copy and paste the above code. You can search for the configuration library in the file, remove the relevant code comments, and modify the certificate instructions.

2. In the above example code, the certificate format is .pfx. If the certificate format is .crt, you need to modify the code as follows:

<Connector port="8443"  protocol="org.apache.coyote.http11.Http11NioProtocol"
              maxThreads="150" SSLEnabled="true" scheme="https">
 <SSLHostConfig sslProtocol="TLS">
        <Certificate certificateFile="/opt/ssl_file/server.crt" certificateKeyFile="/opt/ssl_file/server.key" certificateChainFile="/opt/ssl_file/root.crt" 
                         type="RSA"/>
</SSLHostConfig>
</Connector>

3. Save and close the server.xml file.

web.xml File Confirmation (Optional)

To turn HTTP requests automatically into HTTPS requests during jump, you can perform the operations in this section.

1. Go to the %TOMCAT_HOME%/conf path as the admin and open the web.xml file through a text editor.

2. In the web.xml file, locate the following configuration block and ensure that the value of the <transport-guarantee> tag is CONFIDENTIAL.

<security-constraint>
    <web-resource-collection>
        <web-resource-name>Protected Context</web-resource-name>
        <url-pattern>/*</url-pattern>
    </web-resource-collection>
    <user-data-constraint>
        <transport-guarantee>CONFIDENTIAL</transport-guarantee>
    </user-data-constraint>
</security-constraint>

3. Save and close the web.xml file.

Tomcat Re-startup

Restart the Tomcat server to make configurations effective.

Effect Display

Access https://your_domain:Port numberthrough a browser. If a small lock icon appears on the address bar, the certificate has been successfully installed.

• your_domain specifies the domain name or IP address.

• Port number specifies the value of Connector port configured in section "server.xml File Configuration."

HTTPS Setting

After configuring the SSL certificate in Tomcat for HTTPS access, you need to configure HTTPS settings to ensure the normal WebSocket connection.

Log in to the decision-making platform as the admin and check whether HTTPS Setting appears under System Management > System Setting > General.

• If not, the WebSocket connection has been correctly configured. You do not need to configure it again.

• If so, the Websocket connection is not properly configured. You need to configure it.

Remote Connection Failure

Problem

The designer fails to remotely connect to the HTTPS project, displaying the error "invalid keystore format."

Cause

The certificate of the configured HTTPS project is in the PKCS12 format. However, only the default JKS format is supported on the designer client currently.

Solution

Create a folder named key in the Tomcat folder and place the server.keystore file in the JKS format in the key folder.

Select the server.keystore file in the key folder when performing the remote connection.