{inall}
Using Secure Socket Layer (SSL) communication with the repository manager is an important security feature and a recommended best practice. Secure communication can be inbound or outbound.
Outbound client communication may include integration with
-
a remote proxy repository over HTTPS
-
SSL/TLS secured servers (e.g. for SMTP/email integration)
-
LDAP servers configured to use LDAPS
-
specialized authentication realms such as the Crowd realm
Inbound client communication includes
-
web browser HTTPS access to the user interface
-
tool access to repository content
-
manual or scripted usage of the REST APIs
{inrmonly}
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'.
{pro} includes a specific 'SSL' configuration tab for each repository in the repository configuration documented
in [confignx-sect-manage-repo] 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 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 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.
|
Warning
|
When removing a remote trusted certificate from the truststore, a restart is required before a repository may become untrusted. |
{inrmonly}
{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 SSL Certificates Administration by selecting 'SSL Certificates' in the left-hand 'Administration' menu. The list shows any certificates that are already trusted.
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. 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 -----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. An example of inserting such a certificate is shown in 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 Certificate Details Displayed after Successful Retrieval. Please review the displayed information carefully before clicking 'Add Certificate' to establish the trust store 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.
{inall}
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 {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 '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 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 {nxrm} 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.
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 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.
{inall}
Providing access to the user interface and content via HTTPS is a recommended best practice for any deployment.
You have two options:
-
Using a separate reverse proxy server in front of the repository manager to manage HTTPS
-
Configure the repository manager to serve HTTPS directly
A common approach is to access the repository manager through a dedicated server which answers HTTPS requests on behalf of it - 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.
We will elaborate here on the second approach, which is to use the Eclipse Jetty instance that is distributed with {nxrm} to accept HTTPS connections.
|
Tip
|
Keep in mind that you will have to redo some of these configurations each time you upgrade the repository manager, since they are modifications to the embedded Jetty instance located in '$NEXUS_HOME'. |
To configure the Eclipse Jetty instance to accept HTTPS connections, first enable the file jetty-https.xml to the Jetty startup configuration in wrapper.conf as detailed in [nexus-home-conf].
Next, the HTTP port you want to use for the HTTPS connection has to be defined by setting the application-port-ssl property in nexus.properties.
application-port-ssl=8443
Create a keystore file containing a single certificate that Jetty will use for the HTTPS connections. Instructions are available on the Eclipse Jetty documentation site. You may find the common keytool commands in the SSL Certificate Guide a useful reference.
Adjust the values in the jetty-https.xml file in $NEXUS_HOME/conf to reflect your keystore settings. The default configuration in that file suggests to create a subdirectory NEXUS_HOME/conf/ssl and copy the keystore file in there and rename it to keystore.jks. You can either do that or choose a different location or filename for your keystore file and update the paths for the keystore and truststore in the jetty-https.xml file.
Once this is all in place you can start up the repository manager and access the user interface at e.g., https://localhost:8443/nexus. If you have just created a self-signed certificate, modern web browsers will warn you about the certificate and you will have to acknowledge the fact that the certificate is self-signed. To avoid this behavior, you have to get a certificate signed by a signing authority or reconfigure the web browser.
The repository manager is now available via HTTPS. If desired you can configure automatic redirection from HTTP to
HTTPS by adding usage of jetty-http-redirect-to-https.xml as additional app parameters in wrapper.conf as well
as update the Base URL in your server configuration.