TLS/SSL Offloading with the Gateway

The Kaazing WebSocket Gateway can manage TLS/SSL connections between its clients and its back-end server. There are deployments that require that a different server, such as a load balancer, handle TLS/SSL connections and you can support these scenarios using TLS/SSL offloading and minor changes to the Gateway configuration.

TLS/SSL offloading simply means using a server, such as a load balancer, to act as a TLS/SSL intermediary between clients and the Gateway and encrypt and/or decrypt the requests and responses between the Gateway and its clients. Data that passes between the load balancer and the clients is encrypted. Data that passes between the load balancer and the Gateway is not encrypted.

There are two scenarios discussed below:

Once the Gateway is configured for TLS/SSL Offloading, you simply need to configure your load balancer to use the digital certificates for client connections intended for the Gateway. Here are some examples:

Load Balancer Performs Encryption and Preserves the Host Header

In this scenario, when the Gateway client sends a request, the load balancer decrypts the payload and keeps the host name in the Host request-header field consistent with the client request. For example, the client connects to wss://gateway.example.com/ (on port 443). The load balancer decrypts the message, and forwards the decrypted message to Kaazing Gateway keeping the host name gateway.example.com:443 in the Host header-request field.

When the load balancer forwards the request, it uses the actual host name of the Gateway, which is not gateway.example.com, and the actual port number (80, in this example) for the connection, which might be different than the logical port number used in the Host header-request field (443).

The Gateway service must be configured to accept requests at the host name specified in the Host header-request field, and it must specify which network interface to use when accepting the request. For example, when the client sends a request to wss://gateway.example.com/ (on port 443), the Gateway service must have an accept for wss://gateway.example.com/ and an http.transport for the network interface. Here is a generic example:

<service>
  <accept>wss://gateway.example.com/</accept>
  ...
  <accept-options>
    <http.transport>tcp://@eth0:80</http.transport>
  </accept-options>
</service>

Load Balancer Performs Encryption and Modifies the Host Header

In this scenario, when the Gateway client sends a request, the load balancer decrypts the payload and changes the host name in the Host request-header field to a new host name. For example, the client connects to wss://gateway.example.com/ (on port 443). The load balancer decrypts the message, and forwards the decrypted message to Kaazing Gateway with a new host name gateway.internal.net:80 in the Host header-request field.

When the load balancer forwards the request, it uses the actual host name of the Gateway, which is not gateway.internal.net, and the actual port number (80, in this example) for the connection, which might be different than the logical port number used in the Host header-request field.

The Gateway service must be configured to accept requests at the host name specified in the Host header-request field, and it must specify which network interface to use when accepting the request. For example, when the client sends a request to wss://gateway.example.com/ (on port 443) and the load balancer changes the host name to gateway.internal.net, the Gateway service must have an accept for wss://gateway.internal.net/ and an http.transport for the network interface. Here is a generic example:

<service>
  <accept>wss://gateway.internal.net/</accept>
  ...
  <accept-options>
    <http.transport>tcp://@eth0:80</http.transport>
  </accept-options>
</service>

Notes

See Also