SSL on Nexus 3

Setting up SSL with Nexus Repository Manager 3 on Windows

I wanted to install Nexus Repository Manager 3 and serve traffic over HTTPS, but I ran into some issues. I wanted to share some lessons learned and help people avoid the problems I had.

If you are like me, SSL certificate management can be daunting.  I always think I know what I’m doing, but every time I work on certificate management, I manage to work in circles, until I finally figure out the problem.  If you don’t know anything about web certificates, here’s the 2 minute rundown.

An important term to keep in mind, HTTPS means HyperText Transfer Protocol(HTTP) + (Secure). HTTP, is a protocol that pretty much every website uses to send information to your browser. On top of HTTP, there can sit another protocol that encrypts the data you send. These protocols are called SSL(Secure Sockets Layer) and TLS(Transport Layer Security), for simplicity’s sake, many people generally refer to both of these protocols under the umbrella of SSL, and so that is what I will do below.

SSL provides the ability for encrypted communication between a web browser and a server. To ensure the server is who is who is says it is, and to provide a means for encryption, a certificate needs to be provided.  Essentially, when you browse to an HTTPS site the server provides your computer with a certificate, which provides a number of things, among them, identification information about the server and a public key for your browser to use for encryption purposes.  The server must also have a private key stored for decryption purposes. From there your browser and the server negotiate an encryption method and cipher to use for the session, and you then have a session where all data you send back and forth is encrypted.

Now that we got that out of the way, here’s how to install Nexus Repository Manager 3 on Windows with my lessons learned.

The first thing I did, was follow the installation instructions, listed here, for installing as a service. This worked great, but I ran into trouble with setting up SSL. The network was set up so that they have an F5 sending all traffic going to https://<nexus-url> to http://<name-of-machine-on-our-network>.

F5 by the way, is a brand name for load balancers/reverse proxy’s that can route web requests to internal servers based on the web requests received.

This would “terminate” the SSL connection at the F5 and information will be forwarded in the clear, while inside of our internal network.

Turns out, Sonatype Nexus Repository Manager 3 does not support external SSL termination in this manner.  So we actually have to have internet traffic forwarded directly through the F5, and enable SSL directly on the nexus server.

Now that we have the background out of the way, here is a step by step guide to install the nexus service and enable SSL on windows.

1) Get the latest nexus install zip for windows from their website here

2) Unzip the package to your chosen nexus install location

3) Navigate to Nexus binary file

(Open powershell as administrator): cd <nexus-install-location>/nexus-<version>/bin

4) Install nexus as a service:

nexus.exe /install

2) Start the service

nexus.exe /start

3) Confirm service “nexus” is running

Browse to http://<nexus-machine-fqdn>

4) Stop the service:

nexus.exe /stop

5) Confirm your nexus service is stopped, by opening the “services” program, and refreshing.

6) Get a Certificate/Private/Public key from your network team. Here are a couple examples of how to get your cert in the right format

IMPORTANT NOTE: the proprietary PEM format isn’t super compatible with the keytool command.You can’t take a cert/private key PEM keystore and go directly to a jks keystore, the “keytool” tool will drop the private key. To get around this, you have to convert the “pem” keystore to an intermediary “pkcs12” format first, before converting a second time to the JKS format.

    6a) If you are given a PEM formatted Certificate(cert.pem) that includes a private key, run the following openssl command on powershell:

        i) $ openssl pkcs12 -export -out certificate.pkcs12 -in cert.pem

        ii) Continue to step 7

    6b) If you are given a PCKS12 formatted cert that includes a private key, your certificate is already in a keystore that is compatible with the java keytool command, continue to step 7

    6c) If you are given a PFX formatted cert(certificate.pfx) that includes a private key, this is actually the same format as pkcs12, so you can just continue to step 7

    6d) If you are given a Certificate(cert.crt) and Private key(private.key) separately, run the following openssl command on Powershell yo combine them insto a pkcs12 keystore:

         i) $ openssl pkcs12 -export -out certificate.pkcs12 -inkey private.key -in cert.crt

         ii) Continue to step 7

 

7) Plug your certificate (certificate.pkcs12 or certificate.pfx) into a java keystore named keystore.jks at <nexus-install-location>/nexus-<version>/etc/ssl/keystore.jks, using the following keytool command:

$ keytool -v -importkeystore -srckeystore certificate.pkcs12 -srcstoretype PKCS12 -destkeystore  <nexus-install-location>/nexus-<version>/etc/ssl/keystore.jks -deststoretype JKS

NOTE: Generate and import your PCKS12 certificate into a keystore that uses the SAME password as your certificate.

7)Edit nexus.properties, located at <nexus-install-location>/sonatype-work/nexus3/etc:

1. a) add a property in a new line:  

“application-port-ssl=443”

1. b) uncomment the line starting with “nexus-args” and add “,${jetty.etc}/jetty-https.xml” (without the quotes) to the end of that line

8) Edit <nexus-install-location>/nexus-<version>/etc/jetty/https-config.xml

1. a) Change “password” to whatever your certificate’s password was, this needs to be changed in 3 places.

9) Start “nexus” Service

nexus.exe /start

 

The step by step guide above makes the installation and configuration of SSL fairly simple, but PLEASE follow the “NOTES” above, because those were some of the pain points for me, when installing for the first time.