Repository Management with Nexus

Share

24.1. Managing Outbound SSL Certificates

24.1.1. Trusting SSL Certificates of Remote Repositories

Available in Nexus Pro, Nexus Pro+

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 includes a specific SSL configuration tab for each repository in the repository configuration documented in Section 6.2, “Managing Repositories” to solve this problem. It is displayed when the remote URL of a proxy repository resolves to an https:// location.

The SSL tab shows the details of the remote certificate, as in the example Figure 24.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 24.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 Nexus should consult the Nexus-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 Nexus and the private Nexus 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.

figs/web/ssl-secure-central.png

Figure 24.1. SSL Tab for a Proxy Repository with Remote Server Using HTTPS


[Warning]

When removing a remote trusted certificate from the truststore, a Nexus restart is required before a repository may become untrusted.

24.1.2. Trusting SSL Certificates Globally

Available in Nexus Pro, Nexus Pro+

Nexus Pro and Nexus Pro+ allow 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 24.2, “SSL Certificates Administration” by selecting SSL Certificates in the left-hand Administration menu. The list shows any certificates that are already trusted.

figs/web/ssl-certificates-list.png

Figure 24.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, https://repo1.maven.org. Nexus 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 Nexus 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 -----END CERTIFICATE----- .

An example method to get the encoded X.509 certificate into a file on the command line using keytool is:

keytool -printcert -rfc -sslserver repo1.maven.org > repo1.pem

The resulting repo1.pem file will contain the encoded certificate text that you can cut and paste into the dialog in Nexus. An example of inserting such a certificate is shown in Figure 24.3, “Providing a Certificate in PEM Format”.

figs/web/ssl-pem.png

Figure 24.3. Providing a Certificate in PEM Format


If Nexus 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 24.4, “Certificate Details Displayed after Successful Retrieval”. Please review the displayed information carefully before clicking Add Certificate to establish the trust store addition.

figs/web/ssl-add-server.png

Figure 24.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.

24.1.3. Trusting SSL Certificates Using Keytool

Available in Nexus OSS, Nexus Pro, Nexus 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.

Before you begin the process of trusting a certificate from the command line you will need:

If you are connecting to servers which have certificates that are not signed by a public CA, you will need to complete these steps:

  1. Copy the default JVM truststore file ($JAVA_HOME/jre/lib/security/cacerts) to a Nexus specific location for editing.
  2. Import additional trusted certificates into the copied truststore file.
  3. Configure JSSE system properties for the Nexus 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 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.

wrapper.java.additional.10=-Djavax.net.ssl.trustStore=<truststore>
wrapper.java.additional.11=-Djavax.net.ssl.trustStorePassword=<truststore_password>

Once you have added the properties shown above, restart Nexus and attempt to proxy a remote repository using the imported certificated. Nexus will automatically register the certificates in the truststore file as trusted.