HTTPS configuration for Extend Local Server

Overview

Configuring HTTPS for Extend Local Server involves the use of an NGINX web server in reverse proxy mode placed in front of the service. This approach works regardless of whether Extend Local Server is installed on Microsoft Windows or Linux via Docker - the NGINX configuration is identical in both cases.

Assumptions

This documentation assumes that:

Extend Local Server is already installed and running on its default port 8085 (or a custom port if you changed it during installation).
NGINX can be installed on Linux or Microsoft Windows - on the same machine as Extend Local Server or on a separate dedicated machine.

Requirements

Extend Local Server must be installed and running before you proceed.
NGINX can be installed on a dedicated machine or on an existing machine where Extend Local Server is already running.
A public/private key pair is required, which are installed on NGINX (i.e. NGINX handles the HTTPS protocol).
CAST highly recommends using CA (Certificate Authority) signed certificates, rather than self-signed. This documentation assumes that CA signed certificates are in use.
An unhindered network path must exist between the machine on which NGINX is installed and the machine running Extend Local Server on port 8085, e.g. appropriate firewall rules/VLAN configuration is in place.

Step 1 - Generate public/private keys

A public (e.g.: public_key.crt) and private (e.g. private_key.key) key pair in PEM format is required by NGINX. CAST highly recommends that you do not use self-signed certificates - instead you should use certificates signed by a CA (Certificate Authority).

To generate a private key and a CSR (certificate signing request) which can be sent to a Certificate Authority, run the following command on the machine where NGINX is installed, with elevated permissions (see also https://docs.openssl.org/1.1.1/man1/req/ ):

$ openssl req -new -newkey rsa:2048 -nodes -keyout private_key.key -out csr.csr

Where:

req - indicates that we want a CSR
-new - generates a brand new CSR
-newkey - generates a new private key
rsa:2048 - generates a 2048-bit RSA private key
-nodes - no DES, meaning do not encrypt the private key in a PKCS#12 file
-keyout - defines the name of the private key file
-out - defines the name of the CSR file

You can of course, change any of the parameters to match your own requirements, these are simply suggestions. Ensure that when prompted you fill in the correct FQDN (fully qualified domain name) matching your host machine: this will be used by end users to access Extend Local Server. Retain the private_key.key file and use the contents of the csr.csr file to generate the public_key.crt at your chosen Certificate Authority.

On Microsoft Windows, the openssl command can be run via Git Bash (included with Git for Windows — recommended), Windows Subsystem for Linux (WSL), or a standalone OpenSSL for Windows distribution.

Step 2 - Install NGINX

Install NGINX: this is beyond the scope of this document, instead please consult the following third-party documentation: https://nginx.org/en/docs/install.html .

Step 3 - Configure NGINX

When NGINX is installed, you now need to configure it. There are two parts to this process:

configure the HTTPS element
configure the reverse proxy

Step 3a - Configure HTTPS

See also Configuring HTTPS servers for more information about HTTPS setup with NGINX.

Out of the box, NGINX contains one “vHost” called “default”, serving various default files on port 80. CAST recommends creating a new vHost and using this specifically for the HTTPS requirements. To add a new vHost, create a new empty .conf file in the NGINX configuration directory (in our example the file is named with the machine’s FQDN extend.corp.domain.com):

Linux: /etc/nginx/conf.d/extend.corp.domain.com.conf — use vi, nano, or any text editor
Windows: C:\nginx\conf\conf.d\extend.corp.domain.com.conf — use Notepad or any text editor. Note that the conf.d directory may not exist by default and may need to be created manually; if so, also ensure that the main nginx.conf includes it by adding include conf.d/*.conf; inside the http {} block.

Paste in the following server block configuration to define the HTTPS protocol and then save the file:

server {
    listen 443 ssl;
    server_name extend.corp.domain.com;
    server_tokens off;
    ssl_certificate path/to/public_key.crt;
    ssl_certificate_key path/to/private_key.key;
    ssl_protocols TLSv1.2;
    ssl_ciphers !EDH:!RC4:!ADH:!DSS:HIGH:+AES128:+AES256-SHA256:+AES128-SHA256:+SHA:!3DES:!NULL:!aNULL:!eNULL;
    ssl_prefer_server_ciphers on;
    ssl_ecdh_curve secp384r1;

    location / {

    }
}

Where:

listen 443 ssl - indicates that we want NGINX to listen on all ipv4 addresses on the server, on port 443
server_name - indicates the FQDN on which NGINX will listen for incoming connections
server_tokens off - disables emitting NGINX version numbers on error pages and in the “Server” response header field.
ssl_certificate / ssl_certificate_key - paths to the public_key.crt and private_key.key files on the local disk
ssl_protocols - specifies the protocol to use, a minimum of TLSv1.2 is recommended
ssl_ciphers - sets the SSL ciphers to use. This is only a recommendation and you should choose your own ciphers
ssl_prefer_server_ciphers - specifies that server ciphers should be preferred over client ciphers
ssl_ecdh_curve - specifies a curve for ECDHE ciphers (if you use them)

Step 3b - Configure reverse proxy

The next step involves configuring NGINX to function in reverse proxy mode, i.e. to accept incoming connections and forward them to Extend Local Server.

Edit the vHost configuration file (the same one you created in the previous step), add the following parameters to the location / {} block and then save the file:

location / {
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    proxy_pass http://extend.corp.domain.com:8085/;
    proxy_redirect off;
    proxy_set_header Connection '';
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    chunked_transfer_encoding off;
    client_max_body_size 100M;
}

Where:

proxy_http_version - sets the HTTP protocol version for proxying, use 1.1
proxy_buffering - enables or disables buffering of responses from the proxied server - set to off
proxy_pass - sets the protocol and address/port of the proxied server - set this to the machine on which Extend Local Server is installed, using port 8085 (unless you have customized it). The address can be specified as a domain name or IP address
proxy_cache - defines a shared memory zone used for caching - set to off
proxy_set_header - allows redefining or appending fields to the request header passed to the proxied server - see https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_set_header for more information
chunked_transfer_encoding - allows disabling chunked transfer encoding in HTTP/1.1 - set to off
client_max_body_size - sets the maximum allowed size of the client request body

Additionally, you will also need to add various proxy_set_header parameters to the server {} block created previously:

server {
    ...
    ...
    ...
    proxy_set_header X-Forwarded-For $proxy_protocol_addr; #to forward the original client's IP address
    proxy_set_header X-Forwarded-Proto $scheme; #to forward the original protocol (HTTP or HTTPS)
    proxy_set_header Host $host; #to forward the original host requested by the client
}

Step 4 - Update Extend Local Server public URL

This step is required. If you skip it, the Extend Local Server web UI will attempt to load resources using the original http:// URL, causing mixed-content errors in the browser (blank screen or security warnings).

Extend Local Server stores its own public-facing URL in its configuration and uses it to construct links in the web UI. This URL must be updated to use https:// to match the address now served by NGINX.

Linux via Docker

Stop and remove the existing container, then re-run the docker run command with the public_url environment variable updated to use https://:

docker stop cast_extendproxy
docker rm cast_extendproxy
docker run -d --name cast_extendproxy -p <PORT>:8085 -u 0 -v <DATA_FOLDER>:/opt/cast_extend_proxy/data -e host_port=<PORT> -e public_url=https://<FQDN> -e LOGDEBUG=off -e platform=linux_x64 castimaging/extend-proxy:latest

Where <FQDN> is the same FQDN you declared in the NGINX vHost server_name directive — for example extend.corp.domain.com.

Microsoft Windows

Update the Extend Local Server hostname/URL configuration. See Hostname update for instructions.

Step 5 - Restart NGINX

Linux

Issue the following command:

# systemctl restart nginx

For Linux via Docker installations of Extend Local Server, the container was already restarted in Step 4 - no further action is required for Extend Local Server itself.

Windows

Run the following from the NGINX installation directory (e.g. C:\nginx\) to reload the configuration:

nginx.exe -s reload

Alternatively, stop and restart the process:

nginx.exe -s stop
start nginx.exe

For Microsoft Windows installations of Extend Local Server, restart the CAST_ExtendProxy Windows Service after completing the hostname update in Step 4.

Step 6 - Check access and HTTPS

Check that you can access the Extend Local Server Administration Center over HTTPS from the FQDN you declared in the NGINX vHost, e.g. https://extend.corp.domain.com.

Step 7 - Update CAST Imaging to use the HTTPS URL

If CAST Imaging is already configured to use Extend Local Server via an http:// URL, you must now update it to use the new https:// address served by NGINX. The URL to enter is https://<your_fqdn> (the same FQDN declared in the NGINX server_name directive) — no port number is required as NGINX listens on the standard HTTPS port 443.

To update the URL, use the CAST Extend Settings option in CAST Imaging. See also Configure CAST Imaging to use Extend Local Server for full details.