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:

TEXT

sudo apt update
sudo apt install nginx

→ If a firewall is used, check the configuration:

Check the firewall configuration:

TEXT

sudo ufw app list

The output of the command should look like this:

TEXT

Output
Available applications:
	Nginx Full
	Nginx HTTP
	Nginx HTTPS
	OpenSSH

Enable 'Nginx Full':
TEXT
```
sudo ufw allow ‘Nginx Full’
```
Check the firewall configuration with
TEXT
```
sudo 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:
TEXT
```
sudo systemctl status nginx
```
Check the current configuration of NGINX:
TEXT
```
sudo 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:

TEXT

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.

TEXT

upstream 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:

TEXT

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;

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:

TEXT

#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; 
  } 
}