Resolve Java client HTTPS access failures caused by an incomplete server certificate chain or an outdated JDK truststore. Use OpenSSL to troubleshoot and fix the server certificate chain or update the client JDK. - Certificate Management Service

This document explains why a Java client may fail to access an HTTPS endpoint and report an "unable to find valid certification path" error. This issue typically occurs because the server does not provide a complete certificate chain. This document provides solutions to troubleshoot the issue using OpenSSL and to configure a complete certificate chain on the server.

Symptoms

When a Java application accesses a server endpoint over HTTPS, the connection fails and throws a javax.net.ssl.SSLHandshakeException. The core error message is as follows:

javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Common symptoms of this issue include the following:

Successful access from browsers: The same HTTPS address can be accessed successfully from mainstream browsers, such as Chrome or Firefox, and a security lock icon is displayed.
Access failure from other clients: Non-browser clients, such as Java applications, curl, or wget, report a TLS handshake failure or a certificate verification error when they access the endpoint.

Causes

The SSL/TLS protocol relies on a complete trust chain that extends from the server certificate to a root certificate trusted by the client. This error occurs because the Java client cannot build this complete trust chain.

Cause 1: The server does not provide a complete certificate chain
During the TLS handshake, the server sends only its server certificate (domain name certificate) and omits the required intermediate certificates. Most non-browser clients, including Java clients, cannot automatically download missing intermediate certificates from the network. As a result, authentication fails. Modern browsers, however, have a feature called Authority Information Access (AIA) chasing. This feature allows them to automatically download missing intermediate certificates to complete the certificate chain. This is why browsers can access the endpoint without any errors.
Cause 2: The client's JDK truststore is outdated
The server is correctly configured and sends a complete certificate chain. However, the root certificate of the chain, or a cross-signed root certificate, is not trusted by the client's JDK. This issue usually occurs when the client uses an outdated JDK version. The built-in truststore ($JAVA_HOME/jre/lib/security/cacerts) in an outdated JDK might not include newer root certificates. For example, after DigiCert switched from the G1 root to the G2 root, older JDK versions may not trust the G2 root. For more information, see DigiCert Root Certificate Replacement Announcement.

Solutions

To troubleshoot this issue, check the server first, and then the client. First, use the openssl command to diagnose the server configuration and confirm whether the certificate chain is complete. If the server configuration is correct, check the client environment.

Step 1: Check the server certificate chain configuration

In this step, you can confirm whether the server sends a complete certificate chain during the TLS handshake.

On any device with OpenSSL installed, run the following command. Replace your.domain.com:443 with the actual server endpoint address and port.
```
# Connect to the server and display the certificate chain it provides
openssl s_client -connect your.domain.com:443 -showcerts
```
Analyze the Certificate chain section and the Verify return code in the command output.
- Problem scenario (incomplete certificate chain)
  The output shows only one certificate, which starts with depth=0. The verification return code at the end of the output is not 0. It is typically Verify return code: 20 (unable to get local issuer certificate). This indicates that the server did not provide an intermediate certificate.
```
Certificate chain
 0 s:/CN=your.domain.com
   i:/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
---
Server certificate
-----BEGIN CERTIFICATE-----
(Server certificate content)
-----END CERTIFICATE-----
...
Verify return code: 20 (unable to get local issuer certificate)
```
- Normal scenario (complete certificate chain)
  The output contains multiple certificates. They form an ordered chain from depth=0 (server certificate) to depth=1 (intermediate certificate). The verification return code is Verify return code: 0 (ok).
```
Certificate chain
 0 s:/CN=your.domain.com
   i:/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
 1 s:/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
   i:/C=US/O=DigiCert Inc/CN=DigiCert Global Root CA
---
...
Verify return code: 0 (ok)
```

Step 2: Fix the issue

Based on the diagnosis from Step 1, take the appropriate action.

Scenario 1: Fix an incomplete server certificate chain

If the openssl diagnosis shows an incomplete certificate chain, you must reconfigure the certificate on the server. The server can be a web server, such as Nginx, Apache, or Tomcat, or a load balancer, such as Server Load Balancer (SLB).

Obtain the certificate package file from the certification authority (CA). This file contains the server certificate and all intermediate certificates. This file is typically named fullchain.pem or chain.pem.

Ensure that the content of the certificate package file is in the correct order: the server certificate first, followed by the intermediate certificates.

-----BEGIN CERTIFICATE-----
(Your server certificate content)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate 1 content)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Intermediate certificate 2 content, if it exists)
-----END CERTIFICATE-----

Refer to the official documentation for your web server or gateway. Update its SSL certificate configuration to point to this complete certificate package file. Then, restart the service for the changes to take effect.

Scenario 2: Handle a client JDK truststore issue

If the openssl diagnosis shows that the server certificate chain is complete but the Java client still reports an error, the problem is likely caused by an outdated JDK version on the client.

Recommended solution: Upgrade the JDK Upgrade the JDK for the client application to the latest Long-Term Support (LTS) version, such as the latest updates for JDK 8, 11, or 17. A newer JDK version includes an updated root certificate library. This resolves issues caused by CA root certificate replacements. Upgrading also provides important security fixes and performance improvements.
Temporary solution: Manually import the root certificate into the truststore If you cannot upgrade the JDK immediately, you can manually import the missing root certificate into the cacerts truststore of the current JDK.
1. Obtain the missing root certificate file. For more information, see Download root certificates.
2. Run the following keytool command to import the certificate. The default password for the truststore is changeit.
```
# Replace <path-to-root-ca.crt> with the path to the root certificate file
# Replace $JAVA_HOME with your Java installation directory
keytool -import -alias <give-a-unique-alias> -keystore $JAVA_HOME/jre/lib/security/cacerts -file <path-to-root-ca.crt> -storepass changeit
```

Recommendations

Configuration optimization: Standardize your certificate update process. Each time you update a certificate, ensure that you deploy the complete certificate chain file, not just the domain name certificate file.
Monitoring and alerts: Purchase and enable public domain name monitoring to periodically check the certificate status of your HTTPS service. This helps prevent site downtime caused by expired certificates.