Managing Outbound SSL Certificates
Trusting SSL Certificates of Remote Repositories
Available in Nexus Repository Pro only
When the SSL certificate of a remote proxy repository is not trusted, the repository may be automatically blocked or outbound requests fail with a message similar to PKIX path building failed.
Nexus Repository Manager Pro includes a specific SSL configuration tab for each repository in the repository configuration documented in Managing Repositories to solve this problem. It is displayed when the remote URL of a proxy repository resolves to an
The SSL tab shows the details of the remote certificate, as in the example Figure 23.1, “SSL Tab for a Proxy Repository with Remote Server Using HTTPS”. Use the 'SSL’ tab when the remote certificate is not issued by a well-known public certificate authority included in the default Java trust store. This specifically also included usage of self-signed certificates used in your organization.
To confirm trust of the remote certificate, click the Add to trust store button on the top-right of the SSL tab. This feature is analogous to going to the Figure 23.2, “SSL Certificates Administration” user interface and using the Add button found there. If the certificate is already added, the button can undo this operation and will read Remove from trust store .
The checkbox labelled Use Nexus SSL trust store is used to confirm that the repository manager should consult the private, internal truststore when confirming trust of the remote repository certificate. Without adding the certificate to the private truststore and enabling the checkbox, the repository will not trust the remote.
The default JVM truststore of the JVM installation used to run the repository manager and the private truststores are merged. The result of this merge is used to decide about the trust of the remote server. The default Java truststore already contains public certificate authority trust certificates. If the remote certificate is signed by one of these authorities, then explicitly trusting the remote certificate will not be needed.
Figure 23.1. SSL Tab for a Proxy Repository with Remote Server Using HTTPS
When removing a remote trusted certificate from the truststore, a restart is required before a repository may become untrusted.
Trusting SSL Certificates Globally
Available in Nexus Repository Pro only
Nexus Repository Manager Pro allows you to manage trust of all remote SSL certificates in a centralized user interface. Use this interface when you wish to examine all the currently trusted certificates for remote repositories, or manage certificates from secure remotes that are not repositories.
Access Figure 23.2, “SSL Certificates Administration” by selecting SSL Certificates in the left-hand Administration menu. The list shows any certificates that are already trusted.
Figure 23.2. SSL Certificates Administration
Buttons are provided to Refresh the list from the server, Add a new certificate or Delete the selected certificate.
The Add button presents two options - Paste PEM and Load from server.
There are two types of secure addresses supported by the Load from server option.
The common approach is to choose Load from server and enter the full
https:// url of the remote site, e.g,
. The repository manager will connect using HTTPS and use the HTTP proxy server settings if applicable. Any other protocol than https:// is ignored, and a direct socket connection is attempted in that case.
When the remote is not accessible using
https://, only enter the host name or IP address, optionally followed by colon and the port number. For example:
example.com:8443. In this case repository manager will attempt a direct SSL socket connection to the remote host at the specified port.
Alternatively you can choose the Paste PEM option to configure trust of a remote certificate. Copy and paste the Base64 encoded X.509 DER certificate to trust. This text must be enclosed between lines containing
-----BEGIN CERTIFICATE----- and
An example method to get the encoded X.509 certificate into a file on the command line using
keytool -printcert -rfc -sslserver repo1.maven.org > repo1.pem
repo1.pem file will contain the encoded certificate text that you can cut and paste into the dialog. An example of inserting such a certificate is shown in Figure 23.3, “Providing a Certificate in PEM Format”.
Figure 23.3. Providing a Certificate in PEM Format
If the repository manager can successfully retrieve the remote certificate or decode the pasted certificate, the details will be shown in a dialog allowing you to confirm details as shown in Figure 23.4, “Certificate Details Displayed after Successful Retrieval”. Please review the displayed information carefully before clicking Add Certificate to establish the trust store addition.
Figure 23.4. Certificate Details Displayed after Successful Retrieval
In some organizations, all of the remote sites are accessed through a globally configured proxy server which rewrites every SSL certificate. This single proxy server is acting as a private certificate authority. In this case, you can follow special instructions for trusting the proxy server root certificate , which can greatly simplify your certificate management duties.
Trusting SSL Certificates Using
Available in Nexus Repository OSS and Nexus Repository Pro
Managing trusted SSL certificates from the command line using
keytool and system properties is an alternative and more complex option than using the SSL certificate management features of Nexus Repository Manager Pro.
Before you begin the process of trusting a certificate from the command line you will need:
- a basic understanding of SSL certificate technology and how the Java VM implements this feature
- command line access to the host operating system and the
- network access to the remote SSL server you want to trust from the host running the repository manager. This must include any HTTP proxy server connection details
If you are connecting to servers which have certificates that are not signed by a public CA, you will need to complete these steps:
- Copy the default JVM truststore file (
$JAVA_HOME/jre/lib/security/cacerts) to a repository manager specific location for editing.
- Import additional trusted certificates into the copied truststore file.
- Configure JSSE system properties for the Nexus Repository Manager process so that the custom truststore is consulted instead of the default file.
Some common commands to manually trust remote certificates can be found in our SSL Certificate Guide .
Configuring Nexus Repository Manager With a Custom Truststore
Once you have imported your trusted certificates into a truststore file, you can modify
$NEXUS_HOME/bin/jsw/conf/wrapper.conf to set the system properties necessary to load this file. Make sure to adapt the property numbers (10, 11) to start at the last unused value, which depends on the rest of your configuration.
Once you have added the properties shown above, restart the repository manager and attempt to proxy a remote repository using the imported certificated. The repository manager will automatically register the certificates in the truststore file as trusted.