NGINX: Example Configuration for as Reverse Proxy in IGEL OS with SSL Offloading
This article describes the configuration of the IGEL Universal Management Suite (UMS) and NGINX for SSL offloading. You can use this document when you want the SSL to be terminated not at the UMS Server, but at the load balancer / reverse proxy. The article is based on the example of NGINX. For more information on NGINX, see https://www.nginx.com/resources/glossary/nginx/.
General compatibility is tested with the configurations described in this article. There could be different ways to do the configuration.
As the reverse proxy is an external software we cannot provide full support for each version.
Requirements
Requirements for UMS and certificate configuration for reverse proxy are summarized in Configure the UMS to Integrate Reverse Proxy with SSL Offloading.
Process Overview
The configuration tasks of the reverse proxy are:
UMS / ICG configuration and certificate export as described in Configure the UMS to Integrate Reverse Proxy with SSL Offloading
NGINX Installation (example based on Ubuntu)
NGINX Configuration
NGINX Installation (Example Based on Ubuntu)
→ Install NGINX on your system:
sudo apt update
sudo apt install nginx
→ If a firewall is used, check the configuration:
Check the firewall configuration:
TEXTsudo ufw app list
The output of the command should look like this:TEXTOutput Available applications: Nginx Full Nginx HTTP Nginx HTTPS OpenSSH
Enable 'Nginx Full':
TEXTsudo ufw allow ‘Nginx Full’
Check the firewall configuration with
TEXTsudo ufw status
For the UMS support, it might be necessary to open further ports. For more information on UMS ports, see IGEL UMS Communication Ports.
Get the current state of NGINX:
TEXTsudo systemctl status nginx
Check the current configuration of NGINX:
TEXTsudo nginx -t
NGINX Configuration
The configuration of the server is done in configuration files. In an Ubuntu installation, the main configuration file is /etc/nginx/nginx.conf
.
In this example, a separate configuration file umsSSLOffloading.conf
is used. This file has to be included in the nginx.conf
file:
http {
##
# Basic Settings
##
sendfile on;
...
##
# Virtual Host Configs
##
include /etc/nginx/conf.d/*.conf;
include /etc/nginx/sites-enabled/*;
include /etc/nginx/umsSSLOffloading.conf; # used for configuration
}
The keys and certificates extracted in Configure the UMS to Integrate Reverse Proxy with SSL Offloading can be copied to a directory under /etc/nginx
: for example, /etc/nginx/ssl
– create the directory if it does not exist.
NGINX Configuration File for SSL Offloading
→ Create a new config file umsSSLOffloading.conf
.
This file must contain
upstream server configuration
server configuration
location configuration
This is an example configuration to use with UMS 12 and IGEL OS 12:
The upstream umsserver block defines the UMS Server in the backend.
TEXTupstream umsserver { server 192.168.27.96:8443 max_fails=3 fail_timeout=10s; }
The server block contains the configuration for the NGINX listener and the location.
The UMS web certificate and the client certificate validation should be added here.
Server common configuration:TEXTserver { listen 8443 ssl; # 'ssl' parameter tells NGINX to decrypt the traffic ssl_certificate ssl/ssl-cert-chain.cer; # The Certificate File (Web) ssl_certificate_key ssl/cert-key.key; # The Private Key File (Web) ssl_verify_client optional; ## Client Certificate check must be optional ssl_client_certificate ssl/estca.cer; #certificate for Client Certificate Check access_log /var/log/nginx/ssl-access.log; error_log /var/log/nginx/ssl-error.log;
At least two location definitions are required:
Location definition for all connections via WebSocket. The WebSocket connection requires the forwarding of the client certificate within the header. A second header information to add is the upgrade header which is required for WebSockets.
TEXT# Configuration for connections via WebSocket, the upgrade header information must be written by NGINX location ~ /device-connector/device/(ws-connect|portforwarding) { proxy_pass https://umsserver; proxy_set_header X-SSL-CERT $ssl_client_escaped_cert; # client certificate in current connection proxy_set_header Upgrade $http_upgrade; # Set upgrade header proxy_set_header Connection $connection_upgrade; proxy_ssl_trusted_certificate ssl/ssl-cert-chain.cer; #trusted Cert Chain for UMS connection # TLSv1.3 configuration is recommended but not necessary proxy_ssl_protocols TLSv1.3; }
Location definition for all other connections.
TEXT# Configuration for all other connections location / { proxy_pass https://umsserver; proxy_ssl_trusted_certificate ssl/ssl-cert-chain.cer; proxy_ssl_protocols TLSv1.3; }
The whole configuration file:
#map upgrade header
map %https_upgrade $connection_upgrade {
default upgrade;
'' close;
}
upstream umsserver {
server 192.168.27.96:8443 max_fails=3 fail_timeout=10s;
}
server {
listen 8443 ssl; # 'ssl' parameter tells NGINX to decrypt the traffic
ssl_certificate ssl/ssl-cert-chain.cer; # The Certificate File (Web)
ssl_certificate_key ssl/cert-key.key; # The Private Key File (Web)
ssl_verify_client optional; ## Client Certificate check must be optional
ssl_client_certificate ssl/estca.cer; #certificate for Client Certificate Check
access_log /var/log/nginx/ssl-access.log;
error_log /var/log/nginx/ssl-error.log;
# Configuration for connections via WebSocket, the upgrade header information must be written by NGINX
location ~ /device-connector/device/(ws-connect|portforwarding) {
proxy_pass https://umsserver;
proxy_set_header X-SSL-CERT $ssl_client_escaped_cert;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_ssl_trusted_certificate ssl/ssl-cert-chain.cer;
# TLSv1.3 configuration is recommended but not necessary
proxy_ssl_protocols TLSv1.3;
}
# Configuration for all other connections
location / {
proxy_pass https://umsserver;
proxy_ssl_trusted_certificate ssl/ssl-cert-chain.cer;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_ssl_protocols TLSv1.3;
# proxy_ssl_session_reuse on;
}
}