CA API Gateway 9.1

9.4 9.1

WebSocket Connection Properties

The WebSocket Connection Properties display when you create, modify, or view details of a WebSocket connection.
gateway92
The WebSocket Connection Properties display when you create, modify, or view details of a WebSocket connection.
 
When you save changes to an existing enabled connection, the WebSocket server restarts. Any existing client connections are dropped.
To configure WebSocket connections:
  1. Enter a unique 
    Name
     for the WebSocket connection and an optional
    Description
    .
  2. Select the 
    Enabled
     check box to activate the WebSocket connection.
  3. Select the
    Outbound Only
     check box to make the connection outbound only. The Gateway behaves as a WebSocket client and it will not create an inbound listener for this connection. This disables the Inbound parameters.
    If the connection cannot be established or the connection is lost, the Gateway attempts to reconnect to the WebSocket every 5 minutes (configurable through the
    websocket.outbound.only.connection.reconnect.interval
    cluster property).
    Clear the check box to make the connection inbound and outbound. The Gateway behaves as a WebSocket proxy in this mode.
  4. Configure the Inbound and/or Outbound parameters as necessary.
If you have explicitly configured
ip_tables
 to open a port, remove this modification. The Manage WebSockets Connections task includes parameters to open the port.
Contents:
Configuring the Inbound Parameters
An inbound WebSocket connection listens for a WebSocket client connection request.
 
Setting
Description
Port
Enter the port number to monitor. This port must be unique.
Maximum Connections
Optionally enter the maximum number of allowable connections. Leave this field blank to use the value defined in the WebSocket Cluster Properties cluster property.
Maximum Idle Time
Optionally enter the maximum idle time in milliseconds. Leave this field blank to use the value defined in the WebSocket Cluster Properties cluster property.
Connection Policy
Optionally select the policy that processes the WebSocket message first. If you select NONE, then the handling of the message defaults to the existing service policy.
Example uses of a connection policy:
The connection policy also defines the context variables that can be used to create a dynamic URL in the outbound parameters (see "Outbound Tab" below).
Inbound Policy
Optionally select the policy that processes the WebSocket message sent from the client after the connection has been established. If you select NONE, then the message is forwarded to the back-end server.
If you used the WebSockets feature prior to version 9.2, ensure that any logic in your old Inbound Policy related to authenticating the client/user has been moved to the Connection Policy.
Use SSL
Select this check box to use a secure connection. This enables the 
Client Authentication
 and 
Private Key
 settings. 
Clear this check box to use a standard connection.
TLS Version
If using SSL, optionally choose which TLS protocols to enable for inbound connections. The default is TLS 1.2, 1.1, 1.0. These should suffice in most situations.
(1) Selecting older protocols increase security risk and should be done only for backward compatibility. (2) SSLv2Hello is pseudo-protocol and is intended as a means to communicate with legacy WebSocket servers. If you select SSLv2Hello, be sure to pair it with one of the default TLS protocol versions like TLSv1, TLSv1.1, or TLSv1.2
Cipher Suites
If using SSL, optionally choose which cipher suites to enable for inbound connections. The default cipher suites should suffice in most situations. For more information, see Selecting Cipher Suites. 
Client Authentication
If using SSL, specify whether the client must present a certificate to authenticate:
  • None:
     The client never needs to present a certificate.
  • Optional:
     The client can optionally present a certificate.
  • Required:
     The client must always present a certificate to authenticate.
Configuring Mutual Authentication
The complete steps to configure mutual authentication for inbound connections:
  1. Ensure you have specified a
    Connection Policy
     and that
    Client Authentication
     is set to
    Required
    .
  3. Create users in the appropriate identify provider. For more information, see the appropriate topic:
  4. Import user certificates for the users. For more information, refer to "Configuring the [Certificate] Tab" in each of the appropriate topics:
Private Key
If using SSL, select the server (in this case, Gateway) private key from the drop-down list. The Gateway uses the subject certificate from this private key to respond to the TLS handshake.
 
Configuring Outbound Parameters
An outbound WebSocket connection passes a client message to a protected WebSocket server.
Setting
Description
URL
Enter the URL of WebSocket server in one of the following formats: 
ws://
<hostname>
:
<port><relative_path>
?
<query_parameters>
wss://
<hostname>
:
<port>
<relative_path>
?
<query_parameters>
The
"<relative_path>"
 and
"<query_parameters>"
 are optional. These allow you to specify the exact URL to connect to during runtime. You may reference context variables for all elements to create a dynamic URL. For example:
ws://${server}:${port}/${path}?loginid=${login}
(1) Any context variables that are used in the URL must be defined in the connection policy, which is specified in the Inbound tab. (2) If this field is left blank, the connection is considered a loopback and responds to the client based solely on the inbound definition.
Maximum Idle Time
Optionally enter the maximum idle time in milliseconds. Leave this field blank to use the value defined in the WebSocket Cluster Properties cluster property.
Connection Policy
Optionally select a policy that runs immediately upon connection to the back-end server. If this connection policy fails, then the connection to the back-end server is disconnected.
Outbound Policy
Optionally select the policy that processes the WebSocket message response from the back-end server. If you select NONE, then the message is forwarded to the client.
Use SSL
Select this check box to connect to a secure server. This enables the 
Client Authentication
 and 
Private Key
 settings. 
Clear this check box to use a standard connection.
TLS Version
If using SSL, optionally choose which TLS protocols to enable for outbound connections. The default is TLS 1.2, 1.1, 1.0. These should suffice in most situations. Selecting older protocols increase security risk and should be done only for backward compatibility.
Cipher Suites
If using SSL, optionally choose which cipher suites to enable for outbound connections. The default cipher suites should suffice in most situations. For more information, see Selecting Cipher Suites.
Client Authentication
Select the Client Authentication option to allow the Gateway to present its certificate to the back-end server.
Unlike inbound connections, mutual authentication on outbound connections is controlled by the back-end server. If the back-end server requires a certificate but the Gateway has not been permitted to present one, then the connection fails.
If you are unsure whether the back-end server requires a certificate, enable this option anyway. This helps ensure that the connection to the back-end server is always successful.
Private Key
If Client Authentication is enabled, select the private key. The Gateway uses the subject certificate from this private key to respond to outbound TLS client certificate challenges from the server

Content feedback and comments