...

    proxy_intercept_errors on;
    error_page 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 421 422 423 424 425 426 428 429 431 451 500 501 502 503 504 505 506 507 508 510 511 /custom_error.html;
    location = /custom_error.html {
        internal;
        root /usr/share/nginx/html;
    }

Using letsencrypt to provide certificates

...

Including a redirect to connections to port 80

Leaving port 80 open and including a redirect is widely recommended (including, for example, by Let’s Encrypt: https://letsencrypt.org/docs/allow-port-80/https://letsencrypt.org/docs/allow-port-80/https://letsencrypt.org/ to provide secure connections over HTTPS. Let’s Encrypt is a well known Certificate Authority (CA) that is free to use. Check with your organisation on standards for certificates. You may need to use a different public CA, or an internal CA. Using CAs aside from Let’s Encrypt is well documented on the web. In particular, most public CAs will docuemnt how their certificates can be installed into NGINX.

If you do not use Certbot, skip the section Install certificate using Certbot below, and follow instructions appropriate for your CA.

Installing with apt

The instructions below are based on installation on a Debian-based distribution of Linux, and use the apt command. If you are installing on a RedHat-based distribution of Linux, the equivalent yum commands for NGINX installation are well documented on the web.

Single server, single PhixFlow webapp

The /docs/allow-port-80/. In particular, this allows Let’s Encypt to automatically renew the certificate using the default HTTP-01 challenge.

Hide version number

In this installation, we hide the version number on the default NGINX page. This is a useful secuity measure. Because errors are already redirected to a standard error page (see above), in this installation you are unlikely to see this in a browser. But this can be viewed using a client such a curl that does not apply the port 80 redirect, or by querying for the header information for the service.

Using letsencrypt to provide certificates

The method below uses https://certbot.eff.org/ to issue and install certificates from https://letsencrypt.org/ to provide secure connections over HTTPS. Let’s Encrypt is a well known Certificate Authority (CA) that is free to use. Check with your organisation on standards for certificates. You may need to use a different public CA, or an internal CA. Using CAs aside from Let’s Encrypt is well documented on the web. In particular, most public CAs will docuemnt how their certificates can be installed into NGINX.

If you do not use Certbot, skip the section Install certificate using Certbot below, and follow instructions appropriate for your CA.

Installing with apt

The instructions below are based on installation on a Debian-based distribution of Linux, and use the apt command. If you are installing on a RedHat-based distribution of Linux, the equivalent yum commands for NGINX installation are well documented on the web.

Single server, single PhixFlow webapp

The following instructions assume that NGINX is installed on the same server as PhixFlow itself (i.e. the same server as the tomcat installation), and with a single installation of PhixFlow (a “webapp”). If you have multiple webapps on a single server, multiple webapps across several several servers, or a single webapp on a different server from the reverse proxy, see Multiple PhixFlow webapps or multiple servers below.

...

Set up a domain record

Choose a domain, e.g. phixflow.mycompany.com, and set up an A record on your DNS to point this domain at the public IP address of the server that you are installing NGINX on.

Install NGINX

Install NGINX from the repository

...

Run sudo apt install curl gnupg2 ca-certificates lsb-release to install the prerequisites.

Run the following to set up the repository for mainline packages:

...

. Instructions for various linux distributions can be found here: http://nginx.org/

...

en/linux_packages.html

The example given here is taken from those instructions, and is for installation of NGINX mainline on Ubuntu.

Install prerequisites:

sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring

Import the official NGINX signing key so that the package can be verified:

curl https://nginx.org/keys/nginx_signing.key |

...

Run sudo apt-key fingerprint ABF5BD827BD9BF62 to verify you have the proper key - the output should contain the full fingerprint: 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62.

...

Run sudo apt update and sudo apt install nginx.

...

Open the server to port 80 (HTTP), both in GCP firewalls and ufw on the server.

Follow the instructions here up to Step 7: https://certbot.eff.org/instructions?ws=nginx&os=ubuntubionic. In Step 7, run the first command: sudo certbot --nginx - the final stage of this (installing the certificate into NGINX) will fail. Continuing with the instructions here will install the certificate manually.

Configure NGINX

1. Run sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak to create a default copy of the default configuration.

2. Create a file /etc/nginx/conf.d/phixflow.conf (e.g. with sudo nano /etc/nginx/conf.d/phixflow.conf) and paste in the following, replacing [subdomain] with the appropriate subdomain of the server:

   Code Block

   server { listen 443 ssl; listen [::]:443 ssl ipv6only=on; server_name [subdomain].phixflow.com; proxy_intercept_errors on; error_page 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 421 422 423 424 425 426 428 429 431 451 500 501 502 503 504 505 506 507 508 510 511 /custom_error.html; location = /custom_error.html { internal; root /usr/share/nginx/html; } location / { proxy_pass http://127.0.0.1:8080; } ssl_certificate /etc/letsencrypt/live/[subdomain].phixflow.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/[subdomain].phixflow.com/privkey.pem; include /etc/letsencrypt/options-ssl-nginx.conf; ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; client_max_body_size 40M; add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"; }

3. Create a custom error page

4. Create a file /usr/share/nginx/html/custom_error.html (e.g. with sudo nano /usr/share/nginx/html/custom_error.html) and enter the following contents:

   Code Block
   language html
   <!doctype html> <html> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta http-equiv="X-UA-Compatible" content="IE=11" /> <title>PhixFlow Error</title> </head> <body> <div class="access-error" style="font-family: Verdana, Helvetica, Arial, sans-serif; font-size: 24px; text-align: center; position:absolute; top:300px; width:100%; "> An unexpected error has occurred opening PhixFlow, please contact the support desk. </div> </body> </html>

5. Restart NGINX:

   Code Block
   sudo nginx -s reload sudo service nginx stop sudo service nginx start

   You may need to reboot the server as well in order for NGINX to restart successfully.

6. Run netstat -tln to check the server is listening on port 443 rather than 80.

7. Check the PhixFlow application loads in the browser. Check the security settings in the browser console.

8. Run nginx -V to check the version.

Configure SSL cipher restriction

This is based on recommendations given at: https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations. Note that there is a scheduled audit to review these on a regular basis and update our build instructions to continue to comply with the recommendations.

Open the file at /etc/letsencrypt/options-ssl-nginx.conf. It should look similar to the following:

ssl_session_cache shared:le_nginx_SSL:1m;
ssl_session_timeout 1440m;

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_prefer_server_ciphers on;

ssl_ciphers "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS";

Edit the ssl_protocols parameter to be:

ssl_protocols TLSv1.3;

Edit the ssl_ciphers parameter to be:

ssl_ciphers "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256";

Close and save the file.

Run the following to reload the NGINX configuration:

sudo nginx -s reload

Restart the NGINX service:

sudo service nginx restart

...

A single reverse proxy can handle connections to different webapps (i.e. installations of PhixFlow), whether these are hosted on a single server, or across several servers. See *** for common network configuration for PhixFlow installation. However, whichever configruation you choose, the configuration is the same: you need an IP address and a webapp name to define each PhixFlow installation.

Note that, since NGINX is acting as the the point of SSL termination, that if you specify a PhixFlow installation at an IP address, you must make sure that the route from the reverse proxy to the PhixFlow installation is secure. The suggested configurations in *** will provide this since traffic is sent within a private network.

In the following example, a single reverse proxy on a dedicated server is handling incoming connections to:

...

System name

...

Server IP address

...

Webapp name

...

Production

...

10.154.0.12

...

prod, installed at: /opt/tomcat/webapps/prod

...

UAT

...

10.154.0.13

...

uat, installed at: /opt/tomcat/webapps/uat

...

Dev 1

...

10.154.0.14

...

dev1, installed at /opt/tomcat/webapps/dev1

...

Dev 2

...

10.154.0.14

...

dev2, installed at /opt/tomcat/webapps/dev2

To support connections to all these systems replace the directive

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

in the example phixflow.conf file above with:

    location /prod {
        proxy_pass http://10.154.0.12:8080;
    }

    location /uat {
        proxy_pass http://10.154.0.13:8080;
    }

    location /dev1 {
        proxy_pass http://10.154.0.14:8080;
    }
    
    location /dev2 {
        proxy_pass http://10.154.0.14:8080;
    }

Switching NGINX from stable branch to mainline

...

Run sudo apt remove nginx to remove the current installation of NGINX while preserving the configuration files.

...

Run sudo apt install curl gnupg2 ca-certificates lsb-release to install the prerequisites.

...

Run the following to set up the repository for mainline packages:

echo "deb http://nginx.org/packages/mainline/ubuntu `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

...

Run curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo apt-key add - to import an official NGINX signing key so apt can verify the package's authenticity.

...

Run sudo apt-key fingerprint ABF5BD827BD9BF62 to verify you have the proper key.

...

The output should contain the full fingerprint 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62.

...

Run sudo apt update and sudo apt install nginx.

...

Run sudo rm /etc/nginx/conf.d/default.conf to remove the default configuration.

...

Run sudo vim /etc/nginx/nginx.conf and add include /etc/nginx/sites-enabled/*; below the line include /etc/nginx/conf.d/*.conf;.

...

Run sudo nginx -s reload.

...

Run sudo service nginx stop.

...

Run sudo service nginx start.

...

Run netstat -tln to check the server is listening on port 443 rather than 80.

...

Check the PhixFlow application loads in the browser. Check the security settings in the browser console.

...

 gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Verify the downloaded file:

gpg --dry-run --quiet --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg

The output should contain the full fingerprint 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 as follows:

    pub   rsa2048 2011-08-19 [SC] [expires: 2024-06-14]
          573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
    uid                      nginx signing key <signing-key@nginx.com>

Add the mainline packages to your repository list:

echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] http://nginx.org/packages/mainline/ubuntu `lsb_release -cs` nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

Set up repository pinning:

echo -e "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" | sudo tee /etc/apt/preferences.d/99nginx

Install NGINX:

sudo apt update
sudo apt install nginx

Anchor
installCertificateUsingCertbot installCertificateUsingCertbot

Install certificate using Certbot

• Open the server to port 80 (HTTP), both in GCP firewalls and ufw on the server.

The following instructions are based on the recommended installation of certbot with snap: https://certbot.eff.org/instructions?ws=nginx&os=ubuntubionic. This link also includes alternative instructions for installing certbot if you don’t want to use snap.

These instructions also assume that snap is installed on your system. If it is not, you can following instructions here: https://snapcraft.io/docs/installing-snapd

• Ensure that snapd is up to date:

sudo snap install core; sudo snap refresh core

Install certbot

sudo snap install --classic certbot

Link certbot command to make it accessible:

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Request a certificate:

sudo certbot certonly --nginx

When the final command runs, it will prompt for several respsonses:

• An email address (for urgent renewal and security notices): e.g. security.notifications@mycompany.com

• Terms of service: you must agree to these (press Y)

• Agreement to share your email address with EFF: you can choose either option, i.e. Y or N

• The domain name assigned to this service: e.g. phixflow.mycompany.com

Configure NGINX

Save a backup of the default configuration file:

sudo mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak

Create configuration file for PhixFlow: open editing on a file /etc/nginx/conf.d/phixflow.conf (e.g. with sudo nano /etc/nginx/conf.d/phixflow.conf) and paste in the following, replacing [domin] with your domain, e.g. phixflow.mycompany.com:

server {
    listen 443 ssl;
    listen [::]:443 ssl ipv6only=on;

    server_name [domain];

    proxy_intercept_errors on;
    error_page 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 421 422 423 424 425 426 428 429 431 451 500 501 502 503 504 505 506 507 508 510 511 /custom_error.html;
    location = /custom_error.html {
        internal;
        root /usr/share/nginx/html;
    }

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

    ssl_certificate /etc/letsencrypt/live/[domain]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[domain]/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
    client_max_body_size 40M;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";
}

Create a custom error page: open editing on a file /usr/share/nginx/html/custom_error.html (e.g. with sudo nano /usr/share/nginx/html/custom_error.html) and paste in the following:

<!doctype html>
<html>
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta http-equiv="X-UA-Compatible" content="IE=11" />
        <title>PhixFlow Error</title>
    </head>
    <body>
        <div class="access-error" style="font-family: Verdana, Helvetica, Arial, sans-serif; font-size: 24px; text-align: center; position:absolute; top:300px; width:100%; ">
            An unexpected error has occurred opening PhixFlow, please contact the support desk.
        </div>
    </body>
</html>

Hide version number:

Edit the file /etc/nginx/nginx.conf, and in the http context add the line server_tokens off;. This will result in a file that looks similar to:

...

Restart NGINX:

sudo nginx -s reload
sudo service nginx stop
sudo service nginx start

Notes:

1. You may need to reboot the server as well in order for NGINX to restart successfully.

2. Run netstat -tln to check the server is listening on port 443 and port 80

3. Check the PhixFlow application loads in the browser. Check the security settings in the browser console.

Configure SSL cipher restriction

This is based on recommendations given at: https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations.

Open the file at /etc/letsencrypt/options-ssl-nginx.conf. It should look similar to the following:

ssl_session_cache shared:le_nginx_SSL:10m;
ssl_session_timeout 1440m;
ssl_session_tickets off;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;

ssl_ciphers "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384";

Edit the ssl_protocols parameter to be:

ssl_protocols TLSv1.3;

Edit the ssl_ciphers parameter to be:

ssl_ciphers "TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256";

Close and save the file.

Run the following to reload the NGINX configuration:

sudo nginx -s reload

Restart the NGINX service:

sudo service nginx restart

Anchor
nginxMultipleServerMultiplePhixFlow nginxMultipleServerMultiplePhixFlow

Multiple PhixFlow webapps or multiple servers

A single reverse proxy can handle connections to different webapps (i.e. installations of PhixFlow), whether these are hosted on a single server, or across several servers. See *** for common network configuration for PhixFlow installation. However, whichever configruation you choose, the configuration is the same: you need an IP address and a webapp name to define each PhixFlow installation.

Note that, since NGINX is acting as the the point of SSL termination, that if you specify a PhixFlow installation at an IP address, you must make sure that the route from the reverse proxy to the PhixFlow installation is secure. The suggested configurations in *** will provide this since traffic is sent within a private network.

In the following example, a single reverse proxy on a dedicated server is handling incoming connections to:

To support connections to all these systems replace the directive

    location / {
        proxy_pass http://127.0.0.1:8080;
    }

in the example phixflow.conf file above with:

    location /prod {
        proxy_pass http://10.154.0.12:8080;
    }

    location /uat {
        proxy_pass http://10.154.0.13:8080;
    }

    location /dev1 {
        proxy_pass http://10.154.0.14:8080;
    }
    
    location /dev2 {
        proxy_pass http://10.154.0.14:8080;
    }