Skip to main content

Configuring SSL

Using Secure Socket Layer (SSL) communication with Sonatype Nexus Repository is an important security feature and a recommended best practice. Secure communication can be inbound or outbound.

Outbound client communication may include integration with the following:

  • a remote proxy repository over HTTPS - documented in Repository Management

  • SSL/TLS secured servers - for example, for SMTP/email integration documented in Email Server

  • LDAP servers configured to use LDAPS

  • specialized authentication realms, such as the Crowd realm

Inbound client communication includes the following:

  • web browser HTTPS access to the user interface

  • tool access to repository content

  • and manual or scripted usage of the REST APIs

Outbound SSL - Trusting SSL Certificates of Remote Repositories

When the SSL certificate of a remote proxy repository is not trusted, the repository may be automatically blocked and outbound requests fail with messages similar to PKIX path building failed.

The Proxy configuration for each proxy repository documented in Managing Repositories and Repository Groups includes a section titled Use the Nexus truststore. It allows you to manage the SSL certificate of the remote repository and solves these problems. It is only displayed, if the remote storage uses a HTTPS URL.

The View certificate button triggers the display of the SSL Certificate Details dialog.

Certificate Details Dialog to Add an SSL to the Nexus Truststore

Use the Certificate Details dialog when the remote certificate is not issued by a well-known public certificate authority included in the default Java trust store. This specifically also includes usage of self-signed certificates used in your organization. To confirm trust of the remote certificate, click the Add certificate to truststore button in the dialog. This feature is analogous to going to the SSL Certificates user interface and using the Load certificate button found there as described in Outbound SSL - Trusting SSL Certificates Globally. If the certificate is already added, the button can undo this operation and will read Remove certificate from trust store.

The checkbox labelled Use certificates stored in Nexus to connect to external systems is used to confirm that the repository manager should consult the internal truststore as well as the JVM 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.

Warning

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

Outbound SSL - Trusting SSL Certificates Globally

The repository manager 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 the feature view for SSL Certificates administration by selecting the SSL Certificates menu items in the Security sub-menu in the Administration main menu. A user must have either nx-all or nx-ssl-truststore privileges to access this view.

SSL Certificates Administration Screen

The list shows any certificates that are already trusted. Clicking on an individual row allows you to inspect the certificate. This detail view shows further information about the certificate including Subject, Issuer, and Certificate details. The Delete certificate button allows you to remove a certificate from the truststore.

The button Load certificate above the list of certificates can be used to add a new certificate to the truststore by loading it directly from a server or using a Privacy Enhanced Mail (PEM) file representing the certificate.

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). The repository manager will connect using HTTPS and use the HTTP proxy server settings if applicable. 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 the repository manager will attempt a direct SSL socket connection to the remote host at the specified port. This allows you to load certificates from SMTP or LDAP servers, if you use the correct port.

Alternatively you can choose the Paste PEM option to configure trust of a remote certificate.

A PEM file is a type of Public Key Infrastructure file used for keys and certificates. PEMs are Base64-encoded X.509 DER certificates. Read more in SSL's guide PEM, DER, CRT, and CER: X.509 Encodings and Conversions.

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

You will typically get this file from the certificate owner. 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 contains the encoded certificate text that you can cut and paste into the dialog in the user interface.

If the repository manager can successfully retrieve the remote certificate or decode the pasted certificate, the details will be shown allowing you to confirm details. Please review the displayed information carefully before clicking Add Certificate to establish the truststore addition.

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.

Outbound SSL - Trusting SSL Certificates Using Keytool

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 the repository manager.

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 keytool program

  • 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 that have certificates which 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 $data-dir/custom-truststore.jks for editing. Ensure the file permissions allow read for the repository manager user.

  2. Import additional trusted certificates into the copied truststore file.

  3. Configure JSSE system properties for the 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.

After you have imported your trusted certificates into a truststore file, you can add the JVM parameters configuring the truststore file location and password as separate configuration lines into the file $install-dir/bin/nexus.vmoptions

-Djavax.net.ssl.trustStore=<absolute_path_to_custom_truststore_file>
-Djavax.net.ssl.trustStorePassword=<truststore_password>

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

Inbound SSL - Configuring to Serve Content via HTTPS

Providing access to the user interface and content via HTTPS is a best practice.

You have two options:

  • Use a separate reverse proxy server in front of the repository manager to manage HTTPS

  • Configure the repository manager itself to serve HTTPS directly

Using A Reverse Proxy Server

A common approach is to access the repository manager through a dedicated server which answers HTTPS requests on behalf of the repository manager - these servers are called reverse proxies or SSL/TLS terminators. Subsequently requests are forwarded to the repository manager via HTTP and responses received via HTTP are then sent back to the requestor via HTTPS.

There are a few advantages to using these which can be discussed with your networking team. For example, the repository manager can be upgraded/installed without the need to work with a custom JVM keystore. The reverse proxy could already be in place for other systems in your network. Common reverse proxy choices are Apache httpd, nginx, Eclipse Jetty or even dedicated hardware appliances. All of them can be configured to serve SSL content, and there is a large amount of reference material available online.

Serving SSL Directly

The second approach is to use the Eclipse Jetty instance that is distributed with the repository manager to accept HTTPS connections.

How to Enable the HTTPS Connector

  1. Create a Java keystore file at $data-dir/etc/ssl/keystore.jks which contains the Jetty SSL certificate to use. Instructions are available on the Eclipse Jetty 9 documentation site or our SSL Certificate Guide.

    If your server certificate requires SNI in order to work and you are using Sonatype Nexus Repository version 3.26.0 or greater then follow our instructions for Using a Server Certificate that Requires SNI.

  2. Edit $data-dir/etc/nexus.properties and save the file after making the following changes.

    1. Add a new line containing:

      application-port-ssl=8443

      Change 8443 to your preferred port on which to expose the HTTPS connector. Do not choose a port already in use by another connector or process on the same host.

    2. Uncomment the line containing nexus-args by removing the leading # and space characters. Change the comma delimited nexus-args property value to include ${jetty.etc}/jetty-https.xml. Example edited line with comment character removed and ${jetty.etc}/jetty-https.xml added to the existing values:

      nexus-args=${jetty.etc}/jetty.xml,${jetty.etc}/jetty-http.xml,${jetty.etc}/jetty-https.xml,${jetty.etc}/jetty-requestlog.xml

    3. (Optional) If you do not wish to expose a plain http connector, you can remove ${jetty.etc}/jetty-http.xml, part of the nexus-args value.

    4. Add a new line containing:

      ssl.etc=${karaf.data}/etc/ssl

  3. Edit $install-dir/etc/jetty/jetty-https.xml

    1. Set your keystore passwords appropriately. Make sure all three passwords are the same value ( required ). If you use "password" as your keystore and PrivateKeyEntry password, this step is not necessary.

    2. (Recommended) Before the line containing <Set name="KeyStorePath"> add a new line containing the alias name of your keystore file PrivateKeyEntry. For example if your PrivateKeyEntry is named "jetty", add a line like this:

      <Set name="certAlias">jetty</Set>

  4. Restart the repository manager. Verify HTTPS connections can be established. If Sonatype Nexus Repository starts successfully, but you receive an error connecting to the secure port, then refer to our Troubleshooting Eclipse Jetty SSL Certificates article.

  5. Update the Base URL to use https in your repository manager configuration using the Base URL capability.

How to Disable the HTTP Connector

  1. Edit $data-dir/etc/nexus.properties. Change the nexus-args property comma delimited value to not include ${jetty.etc}/jetty-http.xml. Save the file.

  2. Restart the repository manager. Verify plain HTTP requests are no longer serviced.

Using a Server Certificate Which Requires SNI

If the keystore file referenced by ${jetty.etc}/jetty-https.xml meets the following conditions, custom configuration is required in order for Sonatype Nexus Repository to start:

  • Sonatype Nexus Repository 3.26.0 or newer AND

    • keystore contains more than one server certificate for the same host

    • OR server certificate chosen requires SNI (i.e. has multiple domain names or employs domain wildcards)

Changes required:

  • Edit ${jetty.etc}/jetty-https.xml and save the file after making these changes:

    1. Change the line

      <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">

      to be

      <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server">