Skip to content
CA API Gateway - 9.1
Documentation powered by DocOps

WebSocket Scenarios

Last update March 8, 2019

This topic describes common WebSocket scenarios such as security and message filtering. How your WebSockets behave is defined by your implementation of the WebSocket Server and WebSocket Client.


WebSocket Security Example

In this example, the WebSocket service is prevented from unauthorized use by requiring HTTP Basic Credentials to be passed during the handshake. All messages are audited through the Gateway.

To configure WebSocket security:

  1. Create a policy that requires HTTP Basic Credentials and authenticates against the Internal Identity Provider. Reference: Require HTTP Basic Credential AssertionAuthenticate Against Identity Provider Assertion.
  2. Select Tasks > Additional Actions Manage WebSocket Connections to define a connection. 
    In the Connection Policy field, select the policy created in step 1.
  3. Connect using a WebSocket Client.

What happens? 

The following is a more detailed look as to what occurs in the background when the WebSocket Security example policy is run:

  1. When the client first tries to create a WebSocket, the policy is implemented. 
    If no credentials are submitted, the creation request fails and returns an HTTP 401 Error. The client handles the 401 by prompting for and retrieving credentials and then tries to re-establish the WebSocket.
    With the correct credentials submitted, the connection passes through policy successfully. The connection caches the security header and the socket is established.
  2. All subsequent messages include the security header and the policy is successful.
  3. When the WebSocket is closed, the cache is cleared. Any new connections must provide credentials.

WebSocket Message Filtering Example

This example describes how to filter content as it passes through the CA API Gateway. In this example, the client is an instant message (IM) chat client and the server an IM server.

To configure WebSocket message filtering:

  1. Create a policy that assigns the WebSocket message to the context variable ${filterInput}, which becomes available for message filtering.

    In this policy, the Evaluate Regular Expression Assertion in line 4 uses ${filterInput} to replace all occurrences of the word "dog" with "cat". The configuration of this assertion is shown below.

    The message is returned to the WebSocket processor using the Return Template Response to Requestor Assertion.
  2. Select Tasks > Additional Actions Manage WebSocket Connections to define a connection. 
  3. In the Inbound Policy field, select the policy created in step 1.
  4. Create a connection through the then connect using a WebSocket client.

What happens? 

Similar to the WebSocket security example, when the client connects, the request is analyzed by the service policy where it can be checked for security requirements. Since there are no security requirements in the example policy, the WebSocket is established and HTTP headers are cached (there are none in this case).
Each time a message is sent from the client to the server, "dog" is replaced with "cat".

Was this helpful?

Please log in to post comments.

  1. Samuel Ucich
    2016-10-04 08:47

    For the Security Example, this doesnt' appear to be true:

    'When the client first tries to create a WebSocket, the policy is implemented.'

    My testing shows that the Inbound policy in not invoked when the WebSocket is is invoked on the first and subsequent requests, after the WebSocket is created.

    1. Carl Lum
      2016-10-04 12:05

      Thanks for the comment, Samuel. I am confirming with the Engineering team and will get back to you when I hear from them.

      1. Carl Lum
        2016-10-05 01:49

        Hi Samuel. So to clarify: the policy is implemented when the client first establishes a WebSocket Connection. You can verify this by using the Simple WebSocket Client plugin for Chrome. Enter the URL endpoint and then click Open. Note that the status changes to OPEN. Audit messages in the inbound policy begin logging at this point. This occurs before any messages are actually sent by clicking Send (in the plugin).

  2. Monica Hockelberg
    2016-10-11 11:50

    In Step 2 of the WebSocket Security Example, this instruction:

    "Tasks > Additional Actions > Manage WebSocket Connection"

    Should read:

    "Tasks > Extensions and Add-Ons > Manage WebSocket Connection"

    1. Carl Lum
      2016-10-11 12:49

      Thanks, Monica. That got missed after the Task menu reorg. I've rephrased that sentence to redirect to the Manage WebSocket Connection topic for access information. 

  3. Yanick Girouard
    2019-03-07 09:26

    Typo in first paragraph: WebSocker Server

    1. Malathi Bondili
      2019-03-08 06:01

      Thank you, Yanick. I corrected the typo.