Configure Enterprise Shield™
In this procedure you will learn how to configure Enterprise Shield™ for Kaazing WebSocket Gateway to allow a connection from the DMZ to the trusted network without the need to open any inbound firewall ports. By configuring Enterprise Shield™, you can close all externally facing ports entirely, providing maximum security and zero attack vectors for malicious users seeking to exploit ports in your firewall.
Before you get started with configuration tasks, it is important to understand the concepts behind Enterprise Shield™ by reading the topics in About Enterprise Shield™ and to have a basic understanding of common Gateway topologies, as described in DMZ Gateway to Trusted Network Topology.
The procedure in this topic creates a topology similar to the following figure.

In the figure, the client needs to communicate with the back-end service located on a trusted network, but the client is not authorized to communicate through the firewall. In the Enterprise Shield™ topology, interactions between the client, the DMZ Gateway and internal Gateway, and the back-end service on a trusted network occur as described in the following list:
- The internal Gateway in the trusted network accepts connections for the proxy service to the back-end service, as usual. However because it is configured for a reverse connection, the
accept
does not listen for incoming connections as usual, but rather initiates a connection—remember that it's reversed! Note: Normally anaccept
element in a service definition instructs the internal Gateway to listen on the port for incoming connections. However, with Enterprise Shield™, instead of listening, the internal Gateway initiates a reverse connection to the DMZ Gateway. The reverse connection is achieved by configuring the internal Gateway service to act as a SOCKS client, sending remote bind requests to the DMZ Gateway. This tells the remote side to listen for connections on a particular host and port. That way, when clients' connection requests come in to the DMZ Gateway, the Gateway matches them up with SOCKS bind requests. - The DMZ Gateway starts to connect to the internal Gateway. Typically, the
connect
initiates a connection but because this is configured to be in reverse the DMZ Gateway listens for connections from the internal Gateway. Note: Normally aconnect
element in a service definition instructs the DMZ Gateway to establish an outgoing physical network connection to the specified URI on a remote host machine for each client as it connects to the service. However, with a reverse connection, instead of connecting, the DMZ Gateway listens for an incoming bind request from the internal Gateway. If a bind request matching the specified connect URI is received, then a reverse connection is formed. The reverse connection is achieved by configuring the DMZ Gateway service to act as a SOCKS server, receiving remote bind requests from the internal Gateway. - A client initiates a request to the back-end service.
After the client connects to the DMZ Gateway, a full-duplex connection between the client and the back-end service is established through the DMZ and internal Gateways.
When the DMZ Gateway receives an inbound request, an end-to-end logical connection from the client to the back-end service is in place, and the application functions as usual. The only difference to the back-end service is that its connection comes from the internal Gateway rather than directly from the DMZ Gateway.
The configuration for Enterprise Shield™ is virtually transparent to other areas in your architecture. The end points—the client and the back-end service—remain unchanged and are even unaware that the connection is reversed between the DMZ and internal Gateways. After you add a second Gateway, the only change to your existing architectural components is a minor configuration change on the DMZ Gateway, adding the internal Gateway, and closing the inbound ports in your firewall.
Before You Begin
This procedure is part of Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway
- Become familiar with the DMZ-to-trusted network Gateway topology
- Understand what Enterprise Shield™ is and how it works
- Setting Up Kaazing WebSocket Gateway
- Configure Enterprise Shield™
- Configure Enterprise Shield in a Cluster
To Configure Enterprise Shield™
To configure Enterprise Shield™, you set up the internal Gateway and DMZ Gateway configurations to use the SOCKet Secure (SOCKS) protocol and set the other configuration elements as described for each Gateway in the following procedure.
Note: The following examples use the .net domain (for example, tcp://broker.internal.net:1080) to indicate internal, nonpublic URLs, and use the .com domain to indicate public URLs. All domains and URLs are for example purposes only.Configure the Internal Gateway
The following procedure walks you through the steps to configure the internal Gateway for Enterprise Shield™. See Configuration Examples for a snapshot of the completed service configuration.
- Set up a secure connection in the
accept
element by using WebSocket Secure and port 443, for example: <accept>wss://gateway.example.com:443/path</accept>The public URI wss://gateway.example.com:443/path is configured to accept a connection from the client. In subsequent steps you will see that this URI is used again to configure a logical connection through the DMZ Gateway and to the internal Gateway. Note: Once you configure a secure connection on one Gateway then you must configure every Gateway (including every member in a Gateway cluster) in the same fashion to achieve secure end-to-end connectivity.
- Connect to a back-end service by configuring the
connect
element with a URI for the back-end service, for example:<connect>tcp://internal.example.com:1080</connect>
The internal Gateway connects to the back-end service using tcp://broker.internal.net:1080.
- Set the service
type
toproxy
to connect the internal Gateway to a back-end service:<type>proxy</type>
- Add the following
accept-options
:- Set the HTTP transport to use SOCKS+SSL (recommended) or SOCKS protocol, for example:
<http.transport>socks+ssl://gateway.dmz.net:1080</http.transport>
Enterprise Shield™ requires that you use a transport option (http.transport for WebSocket connections) using SOCKS or SOCKS+SSL protocol to establish the network connections from the DMZ Gateway to the internal Gateway at the center of the Enterprise. Port 1080 is commonly used, but not required.
- Specify the
socks.mode
option in reverse mode so the internal Gateway listens for connections from the DMZ Gateway:
<socks.mode>reverse</socks.mode>
- Set
socks.retry.maximum.interval
to a short time interval, for example:
<socks.retry.maximum.interval>1 second</socks.retry.maximum.interval>
Setting
socks.retry.maximum.interval
handles cases where the DMZ Gateway has not started but the internal Gateway keeps trying to connect to the DMZ Gateway. Use this property to specify the maximum time interval that you want the internal Gateway to wait before retrying the connection to the DMZ Gateway. The setting is the maximum (backoff) interval. Thus, the retry will actually occur at 100ms, then 200ms, then 400ms, and so on until the maximum is reached.
- Set the HTTP transport to use SOCKS+SSL (recommended) or SOCKS protocol, for example:
<http.transport>socks+ssl://gateway.dmz.net:1080</http.transport>
See the Service Reference for more information about the configuration elements.
You've completed configuring the internal Gateway. Now, let's configure the DMZ Gateway.
Configure the DMZ Gateway
The following procedure walks you through the steps to configure the DMZ Gateway for Enterprise Shield™. In such a configuration, a DMZ Gateway or Gateway cluster is deployed in the firewall-protected DMZ peripheral network to service requests from Kaazing WebSocket Gateway clients on the Web. See Configuration Examples for a snapshot of the completed service configuration.
- Set up a secure connection in the
accept
andconnect
elements by using WebSocket Secure and port 443, for example:<accept>wss://gateway.example.com:443/path</accept>
<connect>wss://gateway.example.com:443/path</connect>In the example, the public URI of the
connect
on the DMZ Gateway matches the URI of the accept on the internal Gateway. This is a logical connection. This continues the usage of the public WebSocket Secure URI wss://gateway.example.com:443/path to create a logical connection from the client through the DMZ Gateway and to the internal Gateway.Once you configure secure connections on one Gateway then you must configure every Gateway (including every member in a Gateway cluster) in the same fashion to achieve secure end-to-end connectivity.
- Set up properties that are specific to the service:
- Prepare a connection to the back-end service in advance of the first incoming client connection by setting the
prepared.connection.count
property to at least 1. For example:<prepared.connection.count>1</prepared.connection.count>
In this example, the
prepared.connection.count
property creates one connection to the back-end service when the Gateway starts. - Set the
maximum.recovery.interval
property to at least 1 second:<maximum.recovery.interval>1 second</maximum.recovery.interval>
- Prepare a connection to the back-end service in advance of the first incoming client connection by setting the
- Configure the service
type
toproxy
on the DMZ Gateway. This connects to theproxy
service on the internal Gateway, establishing a connection between the DMZ Gateway and the internal Gateway for each client connection, for example:<type>proxy</type>
- In the
accept-options
, bind the URI in the accept element to the IP address of the network interface. Only the port number is required, for example:<tcp.bind>443</tcp.bind>
- Set the following
connect-options
:- Set the HTTP transport to use SOCKS+SSL (recommended) or SOCKS protocol, for example:
<http.transport>socks+ssl://gateway.dmz.net:1080</http.transport>
Enterprise Shield™ requires that you use a transport option (http.transport for WebSocket connections) using SOCKS or SOCKS+SSL protocol to establish the network connections from the DMZ Gateway to the internal Gateway at the center of the Enterprise. Port 1080 is commonly used, but not required.
- Configure a reverse connection by setting the
socks.mode
option toreverse
:<socks.mode>reverse</socks.mode>
- Set the
socks.timeout
property to 1 higher than the value you set forsocks.retry.maximum.interval
on the internal Gateway.<socks.timeout>2 seconds</socks.timeout>
Note: The settings for
http.transport
andsocks.mode
must match on both the DMZ Gateway and the internal Gateway. - Set the HTTP transport to use SOCKS+SSL (recommended) or SOCKS protocol, for example:
- Optionally, require that the internal Gateway provide a digital certificate to establish a secure connection. You can achieve this higher level of security by setting the
socks.ssl.verify-client
torequired
in the connect options:<socks.ssl.verify-client>required</socks.ssl.verify-client>
In an Enterprise Shield™ topology over
Note: For added security on the client side, use the information and instructions in Require Clients to Provide Certificates to the Gateway to require the client to present a certificate to the DMZ Gateway so that the DMZ Gateway can validate the client's identity.socks+ssl://
, the DMZ Gateway provides the internal Gateway with a digital certificate that the internal Gateway uses to verify the DMZ Gateway’s identity before establishing the secure connection. For added security, you can use thesocks.ssl.verify-client
connect option on the DMZ Gateway to require the internal Gateway to provide a digital certificate to establish a secure connection. This configuration ensures that both the DMZ Gateway and internal Gateway are verified via TLS/SSL before transmitting data, establishing mutual authentication.
See the Service Reference for more information about the configuration elements. You've completed configuring the DMZ Gateway.
Configuration Examples
Here are configuration examples for Enterprise Shield™ in a topology with a DMZ Gateway proxying client connections for an internal Gateway that connects to a back-end service.
Example of an Internal Gateway Configuration
<service> <accept>wss://gateway.example.com:443/path</accept> <connect>tcp://internal.example.com:1080</connect> <type>proxy</type> <accept-options> <http.transport>socks+ssl://gateway.dmz.net:1080</http.transport> <socks.mode>reverse</socks.mode> <socks.retry.maximum.interval>1 second</socks.retry.maximum.interval> </accept-options> </service>
Example of a DMZ Gateway Configuration
<service> <accept>wss://gateway.example.com:443/path</accept> <connect>wss://gateway.example.com:443/path</connect> <type>proxy</type> <properties> <prepared.connection.count>1</prepared.connection.count> <maximum.recovery.interval>1 second</maximum.recovery.interval> </properties> <accept-options> <tcp.bind>443</tcp.bind> </accept-options> <connect-options> <http.transport>socks+ssl://gateway.dmz.net:1080</http.transport> <socks.mode>reverse</socks.mode> <socks.timeout>2 seconds</socks.timeout> <socks.ssl.verify-client>required</socks.ssl.verify-client> </connect-options> </service>
Verify Your Configuration
Verify your configuration is working properly by following the "How do I verify that the Gateway is running?" instructions in Setting Up Kaazing WebSocket Gateway.
Close Inbound Ports
Close the inbound ports on your firewall using the instructions provided by your system.
Verify the End-to-End Configuration
Use a client within the DMZ to test out the internal Gateway before deploying Enterprise Shield™ in your production environment. For help verifying your configuration, follow the instructions in "How do I verify that the Gateway is running?" in Setting Up Kaazing WebSocket Gateway.
Next Step
Congratulations, you got Enterprise Shield™ working! All inbound ports on your firewall are closed so there is no access to the trusted network from the DMZ. No physical address information from the trusted network is exposed in the DMZ configuration. But there is an extra step that must be done if you want to add Enterprise Shield™ to your cluster configuration. See Configure Enterprise Shield™ in a Cluster for more information.
See Also
- About Enterprise Shield™
- Service Element Reference for more information about the elements, properties, and options used in the configuration examples