In this article. you can find an example configuration of F5 BIG IP for SSL Offloading in the IGEL Universal Management Suite (UMS).

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

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.

  1. Configure your UMS. (Configure ICG, if used.)
    1. Activate Forwarding Client Certificate Processing

    2. Set Cluster Address

  2. Create and Export Certificates
    1. Create UMS Web Certificates. (If ICG is used, create Cloud Gateway certificate.)
    2. Export UMS Web Certificate Chain and extract private key and certificate chain. (If ICG is used, export Cloud Gateway certificate chain.)
    3. Export Client Certificate Chain
  3. Configure F5:
    1. UMS Certificates (Web UMS and EST CA)
    2. UMS Backend Node and Pool configuration
    3. iRule for Client Certificate Forwarding
    4. SSL Client Profile
    5. SSL Server Profile
    6. Virtual Server

UMS / ICG Configuration

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 the Reverse Proxy, activate the processing of forwarded Client Certificates on ICG side.

To activate forwarding Client Certificate processing on 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


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

    client-cert-forwarding:
        enabled: true

  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 F5 BIG IP configuration.

  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.

To activate the processing of forwarded Client Certificates on ICG 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


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

    client-cert-forwarding:
        enabled: true

  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 F5 BIG IP configuration.

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

Set Cluster Address

  1. Go to UMS Administration > Global Configuration > Server Network Settings.

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

Create and Export Certificates

Create UMS Web Certificate / Cloud Gateway Certificate

You need to create and use a valid certificate for UMS and Loadbalancer. 

Use Subject alternative names if the IP addresses used for UMS and Loadbalancer are different.


When you use the Reverse Proxy with ICG, use the Cloud Gateway certificate and add the IP or Hostname of the Loadbalancer at the ICG Certificate generation. Use a semicolon to separate the values.

Export UMS Web Certificate Chain and Extract Key and Certificate Chain

  1. Select the current used UMS Web certificate and export the certificate chain.


  2. Set a password and the filename.



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

    1. Open the file and enter the password given for the export. Several entries are shown:


    2. Find the currently used Web key:

  4. Export the Certificate Chain.


  5. Select Entire Chain and export the certificate.


  6. Select Head only and export the certificate to a file for example: ssl-cert.cer.

  7. Export the Private Key.


  8. Enter the Password set at export in UMS.

  9. Select OpenSSL.


    In this example a not encrypted key file is used.

Export Cloud Gateway Certificate Chain and Extract Key and Certificate Chain

  1. If the certificate was added as a Cloud Gateway certificate, export the certificate to IGEL Cloud Gateway keystore format.


  2. Unzip the file.

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


  4. Select the configured key entry and export the private key and certificate chain.

  5. Perform the steps in the section above to extract the files.

Export 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 > Global Configuration > Server Network Settings > Export Client Certificate Chain.

Configure F5

Certificate Management

The UMS Web Certificates und UMS EST CA Certificates must be added in the F5 BIG-IP application.

BIG-IP offers a common Certificate Management.

Configure the UMS Web Certificates / Key:

  1. Add UMS Web Private Key.


  2. Add UMS Web Certificate.


  3. Add UMS Web Certificate Chain.


  4. Add UMS EST CA Certificate


  5. Verify that you have all the imported certificates.


Backend Configuration

The UMS Server must be configured as backend server.

  1. Add a Monitor and configure it for testing if the UMS info URL is online.
    The following properties must be set:

    Type

    HTTPS

    Send String

    GET /info\r\n

    Receive String

    IGEL Universal Management Suite



  2. Create a new Node and set the Address of the UMS Server.


  3. Add Pool. In the pool configuration the monitor and the node server must be at least configured. There is no specific Load Balancing Method recommended.


IRULE to forward the Client Certificate in HTTP Header

Irules is the Script support of F5 BIG-IP.

The Client Certificate can be read from the HTTP_REQUEST. The variable [X509::whole [SSL::cert 0]] contains it in PEM format.

The UMS expects the certificate URL Encoded so it must be encoded:  [URI::encode $ssl_cert]

Forwarding Header Example:

when HTTP_REQUEST {
    set DEBUG 1
 
    if { [SSL::cert count] > 0 } then {
        set ssl_cert [X509::whole [SSL::cert 0]]

        set encodedCert [URI::encode $ssl_cert]
        HTTP::header insert "X-CLIENT-CERT" "$encodedCert"

        if { $DEBUG } {
            log local0. "Client Certificate: $ssl_cert"
            log local0. "Client Certificate Accepted: [X509::subject [SSL::cert 0]]"

            log local0. "Client inserted"
            log local0. [HTTP::header names]
        }       
      
    } else {
        log "No Client SSL Certificate!"
    }
}
CODE

SSL Client Profile

The SSL Client Profile is used to set the SSL configuration for all incoming requests to the Virtual Servers.

  1. Add a new SSL Client Profile and Configure according to the picture below.


  2. Configure the UMS WEB Certificates and Key.


  3. TLSv1.3 is used in the connection from the Device to UMS so the ciphers must be customized.

    Ciphers

    f5-default can be used as Cipher Group

    Options List

    disable the “No TLSv1.3” entry in the Enabled Options list




  4. The necessary customizations for Client Certificate Authentication are:

    Client Certificate

    This value must be set to request

    Trusted Certificate Authorities

    Set to UMS-ESTCA-Certificate

    Advertised Certificate Authorities

    Can be set to UMS-ESTCA-Certificate




SSL Server Profile

The SSL Server Profile is used to set the SSL configuration for all requests to the Backend Servers (UMS).

  1. Create a new SSL Server Profile.

  2. Set the Chain value to UMS Web Certificate Chain.

  3. Set the TLSv 1.3 configuration the same as for the SSL Client Profile above.

Virtual Server Configuration

The Virtual Server defines the Listener in F5 BIG-IP.

  1. Set the following values:

    Type

    Standard

    Source Address

    From which IP are requests allowed. Set it to * if this shouldn’t be evaluated

    Destination Address

    The Address under which this Virtual Server is reachable

    Service Port

    Select the UMS Port


    Protocol

    TCP

    HTTP Profile

    http, required to evaluate the HTTP Header

    SSL Profile (Client)

    Add the earlier created Client SSL Profile

    SSL Profile (Server)

    Add the earlier created Server SSL Profile

    Source Address Translation

    Set it to Auto Map






  2. Add the Pool and iRule to the Virtual Server.