WebSocket traffic

When a user agent requests an upgrade from HTTP or HTTPS to the WebSocket protocol, PingGateway detects the request and performs an HTTP handshake request between the user agent and the protected application.

If the handshake is successful, PingGateway upgrades the connection and provides a dedicated tunnel to route WebSocket traffic between the user agent and the protected application. PingGateway does not intercept messages to or from the WebSocket server.

The tunnel remains open until it is closed by the user agent or protected application. When the user agent closes the tunnel, the connection between PingGateway and the protected application is automatically closed.

The following sequence diagram shows the flow of information when PingGateway proxies WebSocket traffic:

To configure PingGateway to proxy WebSocket traffic, configure the websocket property of ReverseProxyHandler. By default, PingGateway does not proxy WebSocket traffic.

Proxy WebSocket traffic

Set up AM:

Select Services > Add a Service and add a Validation Service with the following Valid goto URL Resources:
- https://ig.example.com:8443/*
- https://ig.example.com:8443/*?*
Register a PingGateway agent with the following values, as described in Register a PingGateway agent in AM:
- Agent ID: ig_agent
- Password: password
  
  Use secure passwords in a production environment. Consider using a password manager to generate secure passwords.

(Optional) Authenticate the agent to AM as described in Authenticate a PingGateway agent to AM.

PingGateway agents are automatically authenticated to AM by a deprecated authentication module in AM. This step is currently optional, but will be required when authentication chains and modules are removed in a future release of AM.

Set up PingGateway:

Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).
Set an environment variable for the PingGateway agent password, and then restart PingGateway:
```
$ export AGENT_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

Add the following route to PingGateway to serve the sample application .css and other static resources:

Linux
Windows

$HOME/.openig/config/routes/00-static-resources.json

%appdata%\OpenIG\config\routes\00-static-resources.json

{
  "name" : "00-static-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}",
  "handler": "ReverseProxyHandler"
}

Add the following route to PingGateway:

Linux
Windows

$HOME/.openig/config/routes/websocket.json

%appdata%\OpenIG\config\routes\websocket.json

{
  "name": "websocket",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(request.uri.path, '^/websocket')}",
  "heap": [
    {
      "name": "SystemAndEnvSecretStore-1",
      "type": "SystemAndEnvSecretStore"
    },
    {
      "name": "AmService-1",
      "type": "AmService",
      "config": {
        "agent": {
          "username": "ig_agent",
          "passwordSecretId": "agent.secret.id"
        },
        "secretsProvider": "SystemAndEnvSecretStore-1",
        "url": "http://am.example.com:8088/openam/"
      }
    },
    {
      "name": "ReverseProxyHandler",
      "type": "ReverseProxyHandler",
      "config": {
        "websocket": {
          "enabled": true,
          "vertx": {
            "maxFrameSize": 200000000,
            "maxMessageSize": 200000000,
            "tryUsePerMessageCompression": true
          }
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "name": "SingleSignOnFilter-1",
          "type": "SingleSignOnFilter",
          "config": {
            "amService": "AmService-1"
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}

For information about how to set up the route in Studio, refer to Proxy for WebSocket traffic in Structured Editor.

For more detail on Vert.x options for WebSocket connections, refer to HttpClientOptions.

Notice the following features of the route:

The route matches requests to /websocket, the endpoint on the sample app that exposes a WebSocket server.
The SingleSignOnFilter redirects unauthenticated requests to AM for authentication.
The ReverserProxyHandler enables PingGateway to proxy WebSocket traffic. After PingGateway upgrades the HTTP connection to the WebSocket protocol, the ReverserProxyHandler passes the messages to the WebSocket server.

Test the setup:
1. In your browser’s privacy or incognito mode, go to https://ig.example.com:8443/websocket.
2. Log in to AM as user demo, password Ch4ng31t.
  
  AM authenticates the user, creates an SSO token, and redirects the request back to the original URI, with the token in a cookie.
  
  The request then passes to the ReverseProxyHandler, which routes the request to the HTML page /websocket/index.html of the sample app. The page initiates the HTTP handshake for connecting to the WebSocket endpoint /websocket/echo.
3. Enter text on the WebSocket echo screen and note that the text is echoed back.

PingGateway 2024.9

WebSocket traffic