Configure the UMS to Integrate Reverse Proxy with SSL Offloading

This article describes the general configurations of the IGEL Universal Management Suite (UMS) for SSL offloading with a load balancer / reverse proxy. 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.

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.

Requirements of Reverse Proxy Configuration

IGEL UMS version 12.04.100 or higher
IGEL OS version 12.3.2 or higher
If the ICG is used: ICG version 12.04.100 or higher
In the case of the Distributed UMS or High Availability installations, the time must be synchronized on all servers.

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.

Process Overview

We advise you to follow the process presented here. Before starting the UMS configuration, take a look at the UMS network connection types described in IGEL Universal Management Suite Network Configuration.

Configure your UMS / ICG:
1. Activate forwarding client certificate processing on UMS / ICG.
2. Modify server network settings and set process configuration.
Configure and export the certificates for the reverse proxy:
1. Configure UMS Web Certificate. / If ICG is used, configure Cloud Gateway certificate.
2. Export the UMS Web certificate chain / If ICG is used, Cloud Gateway certificate chain.
  - Extract private key and certificate chain from the exported certificate. (The necessary file formats depend on the reverse proxy.)
3. Export the EST CA Client Certificate.
4. Export UMS Web Root Certificate / If ICG is used, Cloud Gateway Root Certificate. (Only needed for Azure Application Gateway if trust to the backend server must be verified.)

The next step is the configuration of the reverse proxy. For example configurations, see:

Activate Forwarding Client Certificate Processing on UMS / ICG

If no ICG is used, the processing of forwarded Client Certificates must be activated on UMS side. In case only an ICG is used behind an Azure Application Gateway, activate the processing of forwarded Client Certificates on ICG side.

To activate forwarding Client Certificate processing on UMS:

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
Activate client-cert-forwarding by setting "enabled" to "true" :
```
client-cert-forwarding:
	enabled: true
```
TEXT
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 proxy configuration.
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.

To activate the processing of forwarded Client Certificates on ICG side:

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
Activate client-cert-forwarding by setting "enabled" to "true" :
```
client-cert-forwarding:
	enabled: true
```
TEXT
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 proxy configuration.
Save the configuration changes and restart the ICG server.

Modify Server Network Settings

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

Go to UMS Administration > Global Configuration > Server Network Settings.
Set the Cluster Address.
If you are using a Reverse Proxy, you will need to update the FQDN of the UMS cluster as external address. This value must be set to the FQDN and Port of the Reverse Proxy. For detailed information, see Server Network Settings in the IGEL UMS.
Set the OS 12 device enrollment address (this is the address used for device onboarding).
This configuration must be set for Reverse Proxy without optional Client Certificate verification option like Azure Application Gateway. Set it to the FQDN / IP and Port of the configured listener for Device onboarding.

Set Public Address and Port of the UMS Process Configuration

In case the public address of the UMS differs from the UMS address, the public address and port must be set. This option can be set under UMS Administration > UMS Network > Server. This is essential for device shadowing.

Create UMS Web Certificate / Cloud Gateway Certificate

UMS Web Certificate

Web Certificate from Public CA

In case a Web Certificate from a public CA is used, the issuer public certificate must also be imported as Web Certificate.

You need to create and use a valid certificate for UMS and Loadbalancer. The suggested approach is to use an own certificate for the Reverse Proxy:

Go to UMS Administration > Certificate Management > Web in the UMS Console.
Create the certificate. For details, see Using Your Own Certificates for Communication over the Web Port (Default: 8443). For general information on web certificates, see Web.
The proxy FQDN must be added as Hostname so that in the Certificate it is listed as a Subject Alternative Name.

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. For information on hostnames, Cluster Address, FQDNs, see also Troubleshooting: Error 38 during the Onboarding of an IGEL OS 12 Device.

Cloud Gateway Certificate

When you use the reverse proxy with ICG:

Go to UMS Administration > Certificate Management > Cloud Gateway in the UMS Console.
Create the certificate and add the IP or Hostname of the Loadbalancer at the ICG Certificate generation. Use a semicolon to separate the values.

UMS and ICG Certificates Examples

The network integration of Reverse Proxies and Loadbalancers with the UMS and ICG is a wide area with a lot of possible network settings. Here are two Azure Application Gateway examples listed with appropriate certificate details:

UMS Example

This diagram shows an Azure Application Gateway in front of UMS servers.

These UMS servers are within a Virtual Network and only reachable by a private FQDN. There is one Azure Application Gateway for incoming Device requests and another Reverse Proxy / Loadbalancer (Azure Application Gateway) for UMS Web App and Console requests. So the UMS server is reachable by two different addresses. This must be considered for Web certificate generation.

The private FQDN address is used by the Azure Application Gateway for UMS connection. This address must be set as Common Name (CN) to the UMS Web certificate. The public FQDN must be set for UMS Web App / Console connections to the UMS as Hostname (Subject Alternative Name).

ICG Example

The diagram shows an example of Azure Application Gateway and ICG integration.

In this scenario the Azure Application Gateway connects to the ICG via the same FQDN as the UMS server. The ICG might be in a DMZ so only one FQDN is required.

The Cloud Gateway certificate requires the FQDN as Common Name and as Subject Alternative Name for UMS management.

Export UMS Web Certificate Chain

This certificate must be exported for use in the Listener configuration.

Select the previously configured certificate and click Export certificate chain to keystore.
Set a password and the filename.
Identify the Web key.
The exported keystore file contains several keys and certificates, at least the root and the currently used keys and certificates. A tool like Keystore Explorer can be used to identify the currently used Web key.
How to find the currently used web key with Keystore Explorer
1. Open the file and enter the password given 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.

Extract Private Key and Certificate Chain

Different reverse proxies require different certificate files. For Azure Application Gateway, the key for the listener configuration is required in a PFX formatted file. Parse the exported keystore file to the PFX format. The java keytool command can be used. The command line tool can be found in the UMS installation: (Install Dir)/IGEL/RemoteManager/_jvm/bin
The key alias must be added to the call of command.

keytool -v -importkeystore -srckeystore  yourkeystore.keystore -srcalias mykey -destkeystore myp12file.pfx -deststoretype PKCS12

CODE

For Citrix Netscaler, F5 Big IP and NGINX the certificate chain and the private key need to be exported:

Export the Certificate Chain of the currently used certificate.
Select Entire Chain and X.509 format.
Click Export.
For F5 Big IP: Also select Head only and export the certificate to another file for example: ssl-cert.cer
Export the Private Key.
Enter the password you used in the UMS for the export.
Select OpenSSL.
If required, select Encrypt and enter the corresponding data. In this example, we will use a not encrypted key file.
Click Export.

Export Cloud Gateway Certificate Chain and Extract Key and Certificate Chain

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.
Unzip the file.
Open the keystore.jks file and use the password from the keystorepw file.
Select the configured key entry and export the private key and certificate chain as described in the section Extract Private Key and Certificate Chain.

Export EST CA Client Certificate Chain

The EST CA Client Certificate is required for the Client Certificate check.

The Client Certificate Chain export can be found under: UMS Administration > Server Network Settings > Export Client Certificate Chain.

Export UMS Web Root Certificate for Azure

In the Azure Application Gateway, the Root Certificate is used for the Backend Settings configuration. The root certificate of the used Web certificate must be exported under UMS Administration > Global Configuration > Certificate Management > Web.

Export Cloud Gateway Root Certificate for Azure

In the Azure Application Gateway, the Root Certificate is used for the Backend Settings configuration. The root certificate of the used Cloud Gateway Root certificate under UMS Administration > Global Configuration > Certificate Management > Cloud Gateway.

Download PDF