Azure Application Gateway: Example Configuration as Reverse Proxy in IGEL UMS with SSL Offloading

This article describes the IGEL Unified Management Suite (UMS) configurations and the Azure Application Gateway configurations you need for SSL Offloading.

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.

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

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.

Process Overview

We advise you to follow the process presented here. You will find the steps to take in detail in the sections below.

Understand different connection types.
Create the certificates for the Azure Application Gateway in UMS.
Configure your UMS:
1. Activate Forwarding Client Certificate Processing
2. Modify Server Network Settings
3. Set Process Configuration
Export Certificates for Azure Application Gateway Configuration.
Configure the Azure Application Gateway:
1. Create Azure Application Gateway
2. Add a Routing Rule for Onboarding Connection
3. Add a Routing Rule for the Websocket Connection
4. Check Network Security Group
5. Set Mutual Authentication for WebSocket Connection
6. Add a Rewrite for Client Certificate Forwarding
Troubleshoot certificate error, if needed.

Connection Types Between Device and UMS

For a successful configuration it is important to understand the different connection types.

Device to ICG / UMS Communication

The communication of the devices to UMS or ICG consists of two different types. Regular HTTPS calls for the device registration and a WebSocket connection with Mutual TLS for device management.

Communication via Reverse Proxy

The diagram shows the device to UMS connection via a Network Component like Azure Application Gateway. The required connections are listed for SSL Offloading. The diagram shows one HTTPS connection which is necessary for device onboarding (Client Certificate request) and the following WebSocket connection where Mutual TLS and Client Certificate forwarding is required.

Communication via Azure Application Gateway

Some Reverse Proxies like NGINX support a Mutual TLS configuration with optional Client Certificate check. These Reverse Proxies can handle both required UMS connections with one configured listener. The Azure Application Gateway does not support this feature. The two types of connections used must be handled separately. According to this the Azure Application Gateway configuration must contain two separate listeners with corresponding rules.

The UMS supports the separation of the Onboarding and the WebSocket connections. The following diagram shows an overview of a device to UMS connection via the Application Gateway.

The HTTPS listener for device onboarding could use the standard https Port (443) and forwards direct to UMS.
In this example, the HTTPS listener for WebSocket connection listens on Port 8443 and uses mutual TLS for the Client Certificate Check and adds it to the Request Header, so that the UMS can verify it.

Create Certificate for Azure Application Gateway

The suggested approach for Azure Application Gateway is to use an own certificate which must be added under Certificate Management in the UMS. This certificate can be added under Certificate Management either to the Web or Cloud Gateway section.

The Azure Application Gateway FQDN must be added as Hostname so that in the Certificate it is listed as a Subject Alternative Name.

UMS and ICG Certificates Examples

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

Click for the 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).

Click for the 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.

UMS Configurations

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: (InstallDir)/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
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 Application Gateway 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 Application Gateway configuration.
Save the configuration changes and restart the ICG server.

Modify Server Network Settings

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.
Set the OS 12 device enrollment address (this is the onboarding address).
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.

Export Certificates for Azure Application Gateway Configuration

If no ICG is used behind an Azure Application Gateway, the following certificates have to be exported:

UMS Web certificate chain
UMS Web Root Certificate
EST CA Client Certificate

In case an ICG is used behind an Azure Application Gateway, the following certificates have to be exported:

Cloud Gateway certificate chain
Cloud Gateway Root Certificate for Backend Trust
EST CA Client Certificate

Export UMS Web Certificate Chain Used for Azure Application Gateway Listener

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

Select the configured Azure Web certificate and export the certificate chain.
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.
Click for an example based on Keystore Explorer....
1. Open the file and enter the password given for the export. Several entries are shown:
2. Find the currently used Web key:
Parse the exported keystore file to the PFX format.
Azure Application Gateway requires the key for the listener configuration in a PFX formatted file. The exported keystore file must be converted into this file 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 PKCS1
```
CODE

Export UMS Web Root Certificate

The UMS Web Root Certificate is used for the Backend Settings configuration in Azure. The root certificate of the used Web Certificate must be exported.

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 Cloud Gateway Certificate Chain Used for Azure Application Gateway Listener

If the Azure Application Gateway certificate was added as a Cloud Gateway certificate, export the certificate to IGEL Cloud Gateway keystore format.
Unzip the file.
Open the keystore.jks file and use the password from the keystorepwd file.
Identify the used key entry.
The Azure Application Gateway requires the key for SSL offloading in a PFX file. The exported keystore file can be converted into this file format:

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

CODE

Export Cloud Gateway Root Certificate for Backend Trust

You can export the Cloud Gateway Root certificate via the GUI.

Azure Application Gateway Configuration for the UMS

Create Azure Application Gateway

Assign correct Virtual network and Subnet.
Provide Frontend IP address.
Add backend pool with UMS address. Add the UMS / ICG FQDN or IP.

Add a Routing Rule for Onboarding Connection

Configure a listener:
- Set the Protocol to HTTPS.
- Set the Public IP address.
- The recommended Port value is 443.
Select the PFX file created in Export Cloud Gateway Certificate Chain Used for Azure Application Gateway Listener or Export the UMS Web Certificate Chain Used for Azure Application Gateway Listener, and enter the appropriate password.
Configure Backend targets. The already inserted Backend pool can now be selected and the Backend settings must be added.
Under Add Backend settings, set the Backend protocol to HTTPS and add the UMS Web Port as Backend port.
Select the UMS Web Root Certificate exported in Export UMS Web Root Certificate or Export Cloud Gateway Root Certificate for Backend Trust.
Set the value for Request time-out (seconds) to a value at least 130 seconds.
Verify that the Override with new host name is activated and set Host name override.
Set a Custom probe.

Custom Probe Settings:

Add a Routing Rule for the Websocket Connection

Configure a listener:
- Set the Protocol to HTTPS.
- Set the Public IP address.
- The recommended Port value is 8443.
Select the PFX file created in Export Cloud Gateway Certificate Chain Used for Azure Application Gateway Listener or Export the UMS Web Certificate Chain Used for Azure Application Gateway Listener, and enter the appropriate password.
Add the same Backend Settings as for the Onboarding connection.

Check Network Security Group

Open the Network Security Group used for the Gateway Network and verify if the used Ports are listed
If they are not listed, add them.

Set Mutual Authentication for WebSocket Connection

The mutual authentication can be set in Azure Application Gateway with SSL Profiles:

Add an SSL Profile under SSL settings.
In the Client Authentication part of the Dialog the EST CA Certificate is required, that was exported in Export EST CA Client Certificate Chain.
Add the SSL profile to the WebSocket listener. Not to the Onboarding listener!

Add a Rewrite for Client Certificate Forwarding

The client certificate must be forwarded to the UMS. The Application Gateway can be configured to forward it by a rewrite definition.

Create a rewrite set and assign it to the appropriate rule.
Add the following rewrite rule:

Troubleshooting Certificate Error: Common Name Does Not Match

The UMS or ICG certificate must contain the FQDN of the Backend Server as the Common Name. This value is mandatory for the Azure Application Gateway connection to the Backend. The following error occurs if the certificate is wrong.

In case the Common name cannot be adjusted, it is possible to adopt the Hostname of the UMS / ICG in the Backend Settings. In this case a custom probe must be defined with the given Host name value.

Download PDF