Problems using Maven and SSL behind proxy

java

ssl-certificates

maven-configuration

keytool

byAnton Shumikhin·Oct 23, 2024

Quickly solve your Maven SSL proxy issues by tweaking your settings.xml to include <proxies> settings along with your proxy data. To bypass SSL difficulties, think about appending -Dmaven.wagon.http.ssl.insecure=true to Maven commands. Doing so waives SL checks—a swift solution yet something to be wary of given the security consequences.

Sample settings.xml proxy configuration:

<proxies>
  <proxy>
    <id>my-proxy</id>
    <active>true</active>
    <protocol>https</protocol>
    <host>proxy.example.com</host>
    <port>8080</port>
    <username>myuser</username>
    <password>mypass</password>
  </proxy>
</proxies>

Maven command to bypass SSL validation:

mvn clean install -Dmaven.wagon.http.ssl.insecure=true

For a theoretically safer resolution, forge ahead to the visualization segment for an extensive walk-through on capably processing SSL certificates and truststores.

Proper handling of SSL certificates

SSL issues can be efficiently addressed by viewing and saving the SSL certificate from the repository website, importing it into the Java truststore, and then cofiguring Maven to utilize this truststore. Let's get into it:

Saving the SSL certificate

Load the Maven repository URL in your web browser.
Click the lock icon in the address bar to inspect the certificate and save it in Base 64 X.509 format. This is Java's cup of tea when it comes to certificate formats!

Importing the certificate

Use keytool—Java's toolkit for managing certificates and keystores—to import the certificate into your truststore. Here's an example command:

keytool -import -trustcacerts -file my-repo-certificate.cer -alias "my-cert" -keystore $JAVA_HOME/jre/lib/security/cacerts

The default password for the keystore is "changeit"—or so they wanted us to believe!

To verify the successful import or to list the existing certificates, run:

keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts

Maven configuration

Set up the MAVEN_OPTS environment variable to point to the truststore and include the password:

export MAVEN_OPTS="-Djavax.net.ssl.trustStore=$JAVA_HOME/jre/lib/security/cacerts -Djavax.net.ssl.trustStorePassword=changeit"

For Linux users, remember to mind your path manners—always use absolute path when specifying the truststore.
Ensure you have the right configuration for proxy and SSL in settings.xml.

Still facing issues?

Ponder on the following alternatives if the SSL and proxy issues persist despite trying the aforementioned solutions:

Command Maven to trust all hosts with -Dmaven.wagon.http.ssl.allowall=true. Not secure, but helpful for debugging.
Try using an HTTP Maven repository rather than HTTPS if the issue lies only with the SSL connection.

Don't forget to import root certificates to the Java truststore in case it doesn't include them out of the box.

Pitfalls and their remedies

Working with SSL and proxies might get tangled at times. Let's examine some common pitfalls and their troubleshooting steps:

Dealing with the `SunCertPathBuilderException`

An encounter with this exception usually means something is off with your truststore. Ensure the SSL certificate has been accurately imported into the Java truststore. Use keytool -list to confirm.

Navigating through corporate firewalls

Some corporate firewalls might obstruct access to Maven repositories. In such cases, make sure the access to Maven repository domains is whitelisted, or set SSL inspection to allow these connections.

SSL certificate renewals

Maven Central and other main repositories occasionally refresh their SSL certificates; you might need to fetch the new certificates and redo the import.

Unmasking hidden issues

While dealing with SSL problems, enable detailed logging. Append -X or -e to your Maven commands to reveal the complete stack trace and debug logs—an effective way to unearth the specific SSL issue.

explain-codes / Java / Problems using Maven and SSL behind proxy

Linked

Java HTTPS Client Certificate Authentication



Accept server's self-signed SSL certificate in Java client



How to properly import a selfsigned certificate into Java keystore that is available to all Java applications by default?



Resolving javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed Error?



"pkix path building failed" and "unable to find valid certification path to requested target"



How to import an existing X.509 certificate and private key in Java keystore to use in SSL?



Received fatal alert: handshake_failure through SSLHandshakeException



Proper handling of SSL certificates Pitfalls and their remedies