WebSocket over a Forward Proxy

WebSocket communication can take successfully take place in the presence of forward proxies, providing the client and proxy server have been configured properly to deal with it. This page explains how to configure a Universal Messaging JavaScript client and Apache serving as a forward proxy to permit WebSocket use.

An explicit forward proxy is a forward proxy which the client is configured to use. The client is aware of the presence of this proxy. In these situations it is easier for the client to establish a WebSocket connection with the server for reasons outlined in the section WebSocket Delivery Mode.

Warning: Before detailing how to configure Apache as a forward proxy we warn you that this can be a dangerous thing to do. Before enabling Apache to act as a forward proxy you must secure your server correctly. Failing to do so will provide malicious entities with an open proxy server which are dangerous to both your own network and the rest of the internet.

To proxy requests from your server enable the ProxyRequests directive, located in mod_proxy. An example configuration file configured as a forward proxy would be:

# Example Apache forward proxy configuration
...
Listen 80

# Ensure Proxy Module is Loaded
LoadModule proxy_module path/to/mod_proxy

# Turn on forward proxying
# DO NOT DO THIS UNLESS YOUR FORWARD PROXY IS CORRECTLY SECURED
ProxyRequests On
ProxyVia On
AllowCONNECT 9000 # Allow HTTP CONNECT on the nirvana realm port

<Proxy *>
Order deny,allow
Deny from all
Allow from 127.0.0.1 # Restrict to localhost only
</Proxy>

...

A JavaScript client may then connect using this forward proxy by initialising a session using the following options:

NirvanaSession.start({
...
webSocket : true,
webSocketPort : 9000 // Port of the Universal Messaging interface
});

If the proxy is configured to restrict use of the HTTP CONNECT method then the steps above may fail even if the proxy is explicitly declared to the client browser. In these cases it is possible to take the same steps as detailed below for transparent proxy servers to establish a WebSocket connection.

A transparent forward proxy is an invisible proxy which sits between the client and server. In these cases as the client browser does not know about the presence of this proxy it will not send a HTTP CONNECT request to the proxy when establishing a WebSocket connection. Establishing the connection will likely fail using the configuration above.

Communicating with the server using SSL will alleviate this problem. Transparent proxies will usually by default forward SSL traffic. This will allow us to establish a WebSocket connection.

To do this we must configure apache to allow the HTTP CONNECT header to be sent to the secure nirvana interface. In this case the example is exactly the same as above, except with the line AllowCONNECT 9443 where 9443 is the port of the secure realm interface.

NirvanaSession.start({
...
webSocket : true,
webSocketPort : 9443, // Port of the Universal Messaging secure interface
secure : true
});

To maximise the chance of establishing a successful WebSocket connection we recommend using this secure method of transport over the alternative.