PingGateway

WebSocket traffic with PingAM

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 doesn’t intercept messages to or from the WebSocket server.

The tunnel remains open until it’s 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:

websocket

To configure PingGateway to proxy WebSocket traffic, configure the websocket property of ReverseProxyHandler. By default, PingGateway doesn’t proxy WebSocket traffic.

Proxy WebSocket traffic

  1. Set up AM:

    1. 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/*?*

    2. 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.

  2. Set up PingGateway:

    1. Set up PingGateway for HTTPS, as described in Configure PingGateway for TLS (server-side).

    2. 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.

    3. Make sure PingGateway connects to the sample application over HTTPS with a route to access static resources.

      Learn more in Using the sample application.

    4. Add the following route to PingGateway:

      Linux

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

      Windows

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

      {
  "name": "websocket",
  "baseURI": "https://app.example.com:8444",
  "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": {
        "tls": "ClientTlsOptions",
        "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"
    }
  }
}

      Source: websocket.json

      Learn how to set up the route in Studio in Proxy for WebSocket traffic in Structured Editor.

      Learn more about Vert.x options for WebSocket connections in HttpClientOptions.

      Notice the following features of the route:

      • The route matches requests to /websocket, the endpoint on the sample application that exposes a WebSocket server.

      • The SingleSignOnFilter redirects unauthenticated requests to AM for authentication.

      • The ReverseProxyHandler enables PingGateway to proxy WebSocket traffic and trusts the sample application certificate. It overrides the configuration defined in config.json, so this route use the "tls" setting from the ReverseProxyHandler defined in that file. After PingGateway upgrades the HTTP connection to the WebSocket protocol, the ReverseProxyHandler passes the messages to the WebSocket server.

  3. Test the setup:

    1. In your browser’s privacy or incognito mode, go to https://ig.example.com:8443/websocket and accept the server certificate.

    2. Sign on 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 the screen echoes what you enter.