Skip to main content
Skip table of contents

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:

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:

  1. 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

  2. Enable 'Nginx Full':

    TEXT
    sudo ufw allow ‘Nginx Full’

  3. Check the firewall configuration with

    TEXT
    sudo ufw status

  4. For the UMS support, it might be necessary to open further ports. For more information on UMS ports, see IGEL UMS Communication Ports.

  5. Get the current state of NGINX:

    TEXT
    sudo systemctl status nginx

  6. 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; 
  } 
}


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.