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

A reverse proxy / external load balancer can be used if you manage IGEL OS 12 devices only. See IGEL Cloud Gateway vs. Reverse Proxy for the Communication between UMS 12 and IGEL OS Devices.


The tasks to be done involve:

  • Configuring the Cluster Address and checking UMS web certificates
  • Exporting the UMS web certificate chain
  • Extracting the private key and certificate chain
  • Exporting the client certificate chain (https_trust.keystore)
  • Installing NGINX (example based on Ubuntu)
  • Configuring NGINX
  • Configuring the UMS
  • Configuring the IGEL Cloud Gateway (ICG) if used

Requirements

For extracting keys and certificate chains, you will require a suitable tool like "Keystore Explorer". Please use the latest version of such tools.

Please also make sure that you use Java 17.

Limitations

  • The scan and register command can only be used when an endpoint device can open a direct connection to the UMS. Thus, when an external load balancer / reverse proxy is configured, the scan and register feature might not be usable.

Configuring the Cluster Address and Checking UMS Web Certificates

If you are using an external load balancer / reverse proxy, you have to update the FQDN of the UMS cluster as an external address. This FQDN of the UMS cluster must be included into your web certificate, and the corresponding certificate must be assigned to all UMS servers:

  1. In the UMS Console, set the Cluster Address under UMS Administration > Global Configuration > Server Network Settings > Cluster Address and configure a web certificate for all servers. For detailed information, see Server Network Settings in the IGEL UMS.

    For information on hostnames, Cluster Address, FQDNs, see also Troubleshooting: Error 38 during the Onboarding of an IGEL OS 12 Device. For general information on web certificates, see Web.

    Use subject alternative names (SAN) if the IP addresses or hostnames that are used for the UMS and your load balancer / reverse proxy are different.




  2. In the UMS Console, go to UMS Administration > Global Configuration > Certificate Management > Web and check again that you use a valid certificate for the UMS and your load balancer / reverse proxy. If not, create a valid web certificate.


Exporting the UMS Web Certificate Chain

  1. Select the currently used end certificate and export the certificate chain.


  2. Set the password.


  3. Define the path and the file name.

Extracting the Private Key and Certificate Chain

The exported keystore file contains several keys and certificates, at least the root and the currently used keys and certificates. The currently used key and certificate chain must be extracted from this file. You can use any suitable tool for this, e.g. "Keystore Explorer":

  1. Open the exported file and enter the password you used in the UMS for the export.
    Several entries are shown:


  2. Find the currently used key.
    For this, you can simply compare the ID of the currently used certificate displayed in the UMS and the ID in the certificate details in Keystore Explorer.



Exporting the Certificate Chain

  1. Select the currently used key and export the certificate chain.


  2. Select Entire Chain and X.509 format.


  3. Click Export. 

Exporting the Private Key

  1. Select the currently used key and export the private key.


  2. Enter the password you used in the UMS for the export.

  3. Select OpenSSL.


  4. If required, select Encrypt and enter the corresponding data. In this example, we will use a not encrypted key file.


  5. Click Export.

Exporting the Client Certificate Chain (https_trust.keystore)

The EST CA certificate is required for the client certificate check. This file is stored under [UMS installation directory]/IGEL/RemoteManager/rmguiserver/https_trust.keystore.

  1. Open the keystore, e.g. with the Keystore Explorer.

  2. Use the password igelhttpskey.

  3. Export the certificate with the alias estca.




Installing NGINX (Example Based on Ubuntu)

Install NGINX on your system:

sudo apt update
sudo apt install nginx
TEXT


If a firewall is used, check the configuration:

  1. Check the firewall configuration:

    sudo ufw app list
    TEXT


    The output of the command should look like this:

    Output
Available applications:
	Nginx Full
	Nginx HTTP
	Nginx HTTPS
	OpenSSH
    TEXT

  2. Enable 'Nginx Full':

    sudo ufw allow ‘Nginx Full’
    TEXT

  3. Check the firewall configuration with

    sudo ufw status
    TEXT
  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:

    sudo systemctl status nginx
    TEXT

  6. Check the current configuration of NGINX:

    sudo nginx -t
    TEXT

Configuring NGINX

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
}
TEXT


The extracted keys and certificates 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.

    upstream umsserver {
	server 192.168.27.96:8443 max_fails=3 fail_timeout=10s; 
}
    TEXT

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

    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;
    TEXT
  • 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.

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

    • Location definition for all other connections.

      # Configuration for all other connections
  location / {
 		proxy_pass https://umsserver;
		proxy_ssl_trusted_certificate ssl/ssl-cert-chain.cer;
		proxy_ssl_protocols TLSv1.3; 
 }
      TEXT


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


Configuring the UMS

Activate Forwarding Client Certificate Processing at the UMS

The processing of forwarded client certificates must be activated on the UMS side:

  1. Open the configuration file [UMS installation directory]/IGEL/RemoteManager/rmguiserver/conf/appconfig/application.yml.
    You will see:

    igel:
	client-cert-forwarding:
		enabled: false
		client-cert-forwarded-header: X-SSL-CERT
    TEXT


  2. Activate client-cert-forwarding by setting "enabled" to "true" :

    client-cert-forwarding:
	enabled: true
    TEXT
  3. If required, the forwarding header can be configured. The X-SSL-CERT header value can be changed but be aware to change the corresponding value in the NGINX configuration, see above Location definition for all connections via WebSocket.

  4.  Save the configuration changes and restart the UMS Server service. For details on how you can restart the service, see IGEL UMS HA Services and Processes.

Configuring the IGEL Cloud Gateway (ICG) If Used

If you use an external load balancer / reverse proxy and the IGEL Cloud Gateway, it is necessary to configure the load balancer / reverse proxy in front of the ICG. 

The differences in the configuration are:

  • ICG certificate export (instead of the export of the UMS web certificate)
  • Activate forwarding client certificate processing at the ICG (not the UMS)

Note that the IP or hostname of your load balancer / reverse proxy must be added when generating the ICG certificate. Use a semicolon to separate the values. For more information on ICG installation and certificates, see Installation and Setup.

ICG Certificate Export

  1. In the UMS Console, go to UMS Administration > Global Configuration > Certificate Management > Cloud Gateway and export the ICG certificate chain to IGEL Cloud Gateway keystore format:


    The keystore.icg file will be saved.

  2. Unzip the keystore.icg file.


  3. Open the keystore.jks file and use the password from the keystorepwd file.


  4. Select the configured key entry and export the certificate chain (Entire Chain, X.509 format) and the private key (OpenSSL).


  5. Proceed further as described above starting with Exporting the Client Certificate Chain (https_trust.keystore).

Activate Forwarding Client Certificate Processing at the ICG

The processing of forwarded client certificates must be activated on the ICG side, not the UMS side:

  1. Open the configuration file [UMS installation directory]/IGEL/icg/usg/conf/application-prod.yml.
    You will see:

    igel:
	client-cert-forwarding:
		enabled: false
		client-cert-forwarded-header: X-SSL-CERT
    TEXT


  2. Activate client-cert-forwarding by setting "enabled" to "true" :

    client-cert-forwarding:
	enabled: true
    TEXT
  3. If required, the forwarding header can be configured. The X-SSL-CERT header value can be changed but be aware to change the corresponding value in the NGINX configuration, see above Location definition for all connections via WebSocket.

  4.  Save the configuration changes and restart the ICG server.