Problem
Visit help.sonatype.com for documentation on Nexus Repository version 3.
Your Nexus Repository 3 instance is configured to use an HTTP proxy server that rewrites SSL certificates for secure (HTTPS) remote hosts.
The identity of each host certificate remains unique, but your HTTP proxy server modifies the certificate chain of the remote certificate such that your HTTP proxy server acts like an internal certificate authority.
Since Nexus Repository 3, by default, only knows about certificate authorities in the JVM cacerts file, it will not implicitly trust certificates issued by your proxy server. This can result in connection errors to remote hosts that include messages similar to:
sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target >
PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target >
unable to find valid certification path to requested target
Resolution
When you first encounter these errors, you may be inclined to start adding each certificate your proxy server generates to your Nexus Professional trust store. This can work, but is not ideal for several reasons.
- This is potentially a fair amount of overhead if you have many repositories.
- When new repositories get added, it is easy to forget to explicitly trust the remote certificate, especially if you have multiple users maintaining your Nexus instance
- Not all outbound HTTPS connections are for repositories, therefore some problems may not be noticeable unless you closely examine the nexus.log for errors and research what host certificates to trust
- HTTP proxy servers can generate new certificates for the same remote on a configured schedule - a policy enforced by your proxy server administrators and beyond the control of a Nexus Administrator
A more reliable solution is to trust the proxy server certificate once, essentially treating it as an authority for every certificate it issues.
To do this, execute a command to get the PEM formatted certificate of your proxy server. For example:
keytool -J-Dhttps.proxyHost=<proxy_hostname> -J-Dhttps.proxyPort=<proxy_port> -printcert -rfc -sslserver <remote_host_name:remote_ssl_port>
Replace <proxy_hostname> and <proxy_port> with the HTTP proxy server that Nexus is configured with under Server Administration -> System -> HTTP. Replace <remote_host_name:remote_ssl_port> with one of the remote host and port having the certification problem. You can omit the port if it is the default 443.
You should see at least two entries printed by the above command. Take the last certificate content printed and copy it entirely to your clipboard. This should be your proxy server's certificate, added to the end of the certificate chain.
The copied certificate content should start with -----BEGIN CERTIFICATE----- and end with-----END CERTIFICATE-----.
Then in the Nexus UI, go to Server Administration -> Security -> SSL Certificates and click Add Certificate and choose Paste PEM. Paste the certificate contents to the dialog that opens.
Click Load Certificate. Verify the certificate contents in the next window. Verify the Issuer details listed are from your proxy server certificate. When you are satisfied click Add Certificate to Truststore.
If you have previously added host specific certificates to the Nexus Repository 3 trust store that have an Issuer of your proxy server, you can optionally delete those explicit certificate entries.
Certain features such as proxy repositories, require an explicit declaration that they consult the Nexus Trust Store to verify a remote certificate chain. For example, proxy repositories must still have the Use the Nexus Repository truststore checked on the proxy repository configuration.