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:
Activate forwarding client certificate processing on UMS / ICG.
Modify server network settings and set process configuration.
Configure and export the certificates for the reverse proxy:
Configure UMS Web Certificate. / If ICG is used, configure Cloud Gateway certificate.
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.)
Export the EST CA Client Certificate.
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:
NGINX: Example Configuration for as Reverse Proxy in IGEL OS with SSL Offloading
F5 BIG IP: Example Configuration as Reverse Proxy in IGEL UMS with SSL Offloading
Azure Application Gateway: Example Configuration as Reverse Proxy in IGEL UMS with SSL Offloading
Citrix Netscaler: Example Configuration as Reverse Proxy in IGEL UMS with SSL Offloading
Monitoring - Health Probe of UMS / ICG
Load balancers use health probes for detecting the online state of the backends to distribute data to them. If a custom HTTP probe should be used for monitoring the UMS/ICG service, the following URLs can be configured for testing:
UMS:
https://UMS_URL:8443/info
orhttps://UMS_URL:8443/ums/check-status
ICG:
https://UMS_URL:8443/usg/server-status
orhttps://UMS_URL:8443/usg/check-status
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:TEXTigel: client-cert-forwarding: enabled: false client-cert-forwarded-header: X-SSL-CERT
Activate
client-cert-forwarding
by setting "enabled
" to "true
" :TEXTclient-cert-forwarding: enabled: true
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:TEXTigel: client-cert-forwarding: enabled: false client-cert-forwarded-header: X-SSL-CERT
Activate
client-cert-forwarding
by setting "enabled
" to "true
" :TEXTclient-cert-forwarding: enabled: true
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 How to Use Your Own Certificates for Communication over the Web Port (Default: 8443) in IGEL UMS . For general information on web certificates, see Web Certificates in the IGEL UMS .
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:
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.
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
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:
Thekeystore.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.