Using NGINX to add SSL to the WebAdmin and WebUI
Some time ago we introduced both the WebAdmin and the WebUI. The first one is the Plastic SCM's server administration and monitoring web panel, while the second is a nice web interface to browse repository content (including code reviews and even semantic diffing!) For now, both interfaces lack SSL.
Our friend trx contributed in our forum with a quick guide on how to add SSL to the WebAdmin and WebUI using NGINX. In this blogpost, I'll walk you through an extended version of trx's guide, covering how to customize the WebAdmin's default port, install NGINX, generate a self-signed certificate (in case you don't want to invest in buying one from a trusted CA), and configuring NGINX to act as a reverse proxy for the Plastic SCM's WebAdmin and WebUI web interfaces, adding SSL support to them.
Getting the machine ready
For this guide, I'll use one machine only, but adjusting the URLs as necessary, you could use two: one machine would host the Plastic SCM server, and the other one, the reverse NGINX proxy.
My Operating System of choice will be Ubuntu 17.10, but these steps should be valid (or easily adaptable) to the rest of UNIX-like OS, and even to other families such as Windows and macOS.
In any case, what you need to understand is that the only traffic under HTTPS is between the user and the NGINX reverse proxy. The traffic between NGINX and Plastic's web interfaces will still use HTTP, so ensure that part of your setup is protected for your use case.
Installing and configuring the Plastic SCM server
You will obviously need a running Plastic SCM server. You will find the how-to guide to your platform on our downloads portal, but I added this step because there is something I want to point out.
By default, the WebAdmin binds to your 7178 port (and so does the WebUI; it is accessible from a different path). In case you already have something running on that port, you can configure it through your server.conf configuration file. If you installed the Plastic SCM server on the default paths, that file should be located at:
- Windows:
C:\Program Files\PlasticSCM5\server\server.conf - GNU/Linux:
/opt/plasticscm5/server/server.conf - macOS:
/Applications/PlasticSCMServer.app/Contents/MonoBundle/server.conf
The key you're looking for in the image is WebAdminToolPort. If you decide to change the port, you will need to restart the server for the changes to take effect. You can find out how here in the Administrator's Guide. Please note that the StartWebAdminTool setting should also be set to true, which is its default value!
Installing NGINX
If you are using a Debian-based OS, installing NGINX should be as easy as executing the following command:
$ sudo apt-get update && sudo apt-get install nginx
If you are using macOS, you can install NGINX using the mighty brew package manager:
$ brew install nginx
And if you are using Windows, you will find the binaries on their download's portal. This is the last time I'll cover macOS and Windows, centering the rest of the post on Ubuntu 17.10.
Once installed, NGINX will bind to the port 80 by default. You can check that it is up and running by navigating to http://localhost, as I did here:
Creating a self-signed SSL certificate
With OpenSSL, which is installed by default on Ubuntu 17.10, this should be as easy as executing a couple of commands. You can customize the output files part of the command but remember the paths you use! I followed the steps detailed at this awesome DigitalOcean's guide, where you'll find extended information. I'll only detail the most important bits here.
First, we'll create a self-signed certificate valid for a year:
$ sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/nginx.key -out /etc/ssl/private/nginx.crt
The command will ask you to fill-in some fields. The most important one is the Common Name, which will indicate the domain(s) or IP addresses where the certificate is valid. For this example, I used the 127.0.0.1 IP, but yours could be a domain, or the machine name.
Creating a Diffie-Hellman group
Now, we'll create a Diffie-Hellman group. You can learn more about Diffie-Hellman in the SSL context in this nice security.stackexchange.com answer.
$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048
It will take a while to complete, so be patient. Once you're done, we can start configuring our NGINX install!
Configuring NGINX to use SSL
Instead of putting all our configuration in the same file, we are going to split it, so it can be easily maintained and tweaked if needed.
First, we are going to create a configuration snippet to tell NGINX where it should look for the certificate file and its key. To do this, we'll create a file with path /etc/nginx/snippets/self-signed.conf with the following content:
ssl_certificate /etc/ssl/private/nginx.crt; ssl_certificate_key /etc/ssl/private/nginx.key;
Then, we'll create a configuration snippet with the SSL configuration at /etc/nginx/snippets/ssl-params.conf. Following DigitalOcean's example, we also took the default configuration provided on Cipherli.st. You can copy and paste it if you want.
ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_prefer_server_ciphers on; ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH"; ssl_ecdh_curve secp384r1; ssl_session_cache shared:SSL:10m; ssl_session_tickets off; ssl_stapling on; ssl_stapling_verify on; resolver 8.8.8.8 8.8.4.4 valid=300s; resolver_timeout 5s; add_header X-Frame-Options DENY; add_header X-Content-Type-Options nosniff; ssl_dhparam /etc/ssl/certs/dhparam.pem;
Now, it is time to adjust NGINX so it uses these two files. Our main goal is to make it a reverse SSL proxy to the WebAdmin and WebUI, so if anyone tries to navigate under HTTP, we should redirect them to use the HTTPS version.
With that in mind, we'll make a backup of our /etc/nginx/sites-available/default file and edit it. I'll paste here my entire configuration and explain the most important lines later.
$ sudo cp /ect/nginx/sites-available/default /ect/nginx/sites-available/default.bak
And here is the default content after editing it:
server {
listen 80 default_server;
listen [::]:80 default_server;
server_name 127.0.0.1;
return 302 https://$server_name$request_uri;
}
server {
listen 443 ssl http2 default_server;
listen [::]:443 ssl http2 default_server;
include snippets/self-signed.conf;
include snippets/ssl-params.conf;
location / {
proxy_pass http://localhost:7178;
}
}
First, we configure the server name to the IP (or name, or domain) we configured on the SSL certificate. Then, we'll return a 302 moved temporarily to HTTPS if someone tries to navigate through the insecure version. If everything works OK, you can change the 302 for a 301.
On the second server section, we tell NGINX to listen to HTTPS through the default port for the protocol, including the snippets we created before.
The last and most important part is the location one, where we indicate that when users navigate to the root path (/) it should act as a proxy for the WebAdmin URL.
Now, we can check that the files have the correct syntax by executing the following:
$ sudo nginx -t
Which should output something like the following:
Please note that the first warning is OK. Because we signed our own certificate, it can't use OCSP stapling.
Now, we are ready to restart the NGINX service!
$ sudo service nginx restart
Wrapping up!
If everything went OK, now you can navigate to https://127.0.0.1, and the WebAdmin should load under HTTPS.
You'll probably see an alert message on your browser warning you that there were problems with the certificate. Luckily you can add a security exception for it, as you already know that that certificate is safe ;-)
I'd like to thank user trx again for the guide. Its participating users like you that makes this an awesome job :-)
As always, if you have any problems or doubts, don't hesitate to get in touch through the comments, on Twitter at @plasticscm, or through email, at support@codicesoftware .com. We'll get back to you soon!
0 comentarios: