---
title: Proxy WebSocket traffic
description: When a user agent requests an upgrade from HTTP or HTTPS to the WebSocket protocol, IG detects the request and performs an HTTP handshake request between the user agent and the protected application.
component: pinggateway
version: 7.2
page_id: pinggateway:gateway-guide:websocket
canonical_url: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/websocket.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2022-05-09T11:53:52Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/gateway-guide/websocket.html
section_ids:
  vert_x_specific_configuration_for_websocket_connections: Vert.x-specific configuration for WebSocket connections
---

# Proxy WebSocket traffic

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

If the handshake is successful, IG upgrades the connection and provides a dedicated tunnel to route WebSocket traffic between the user agent and the protected application. IG 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 IG and the protected application is automatically closed.

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

![Flow of information to proxy WebSocket traffic.](_images/websocket.svg)

To configure IG to proxy WebSocket traffic, configure the `websocket` property of [ReverseProxyHandler](../reference/Handlers.html#ReverseProxyHandler). By default, IG does not proxy WebSocket traffic.

Proxy WebSocket traffic

1. Set up AM:

   1. (From AM 6.5.3) Select Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:

      * `http://ig.example.com:8080/*`

      * `http://ig.example.com:8080/*?*`

   2. Select Applications > Agents > Identity Gateway, and add an agent with the following values:

      * Agent ID: `ig_agent`

      * Password: `password`

        For AM 6.5.x and earlier versions, set up an agent as described in [Set up an IG agent in AM 6.5 and earlier](preface.html#setup-agent-65).

2. Set up IG:

1) Add the following route to IG, to serve .css and other static resources for the sample application:

   * Linux

   * Windows

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

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

   ```json
   {
     "name" : "sampleapp-resources",
     "baseURI" : "http://app.example.com:8081",
     "condition": "${find(request.uri.path,'^/css')}",
     "handler": "ReverseProxyHandler"
   }
   ```

2) Add the following route to IG:

   * Linux

   * Windows

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

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

   ```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/",
           "version": "7.2"
         }
       },
       {
         "name": "ReverseProxyHandler",
         "type": "ReverseProxyHandler",
         "config": {
           "websocket": {
             "enabled": 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, see [Proxy for WebSocket traffic in Structured Editor](../studio-guide/examples-se.html#example-websocket-se).

   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 IG to proxy WebSocket traffic, and, after IG upgrades the HTTP connection to the WebSocket protocol, passes the messages to the WebSocket server.

     1. Test the setup:

3) If you are logged in to AM, log out and clear any cookies.

4) Go to <http://ig.example.com:8080/websocket>. The SingleSignOnFilter redirects the request to AM for authentication.

5) 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`.

6) Enter text on the WebSocket echo screen, and note that the text is echoed back.

## Vert.x-specific configuration for WebSocket connections

For IG in standalone mode, configure Vert.x-specific configuration for WebSocket connections, where IG does not provide its own first-class configuration. Vert.x options are described in [HttpClientOptions](https://vertx.io/docs/apidocs/io/vertx/core/http/HttpClientOptions.html).

The following example configures Vert.x options for Websocket connections:

```json
{
  "type": "ReverseProxyHandler",
  "config": {
    "websocket": {
      "enabled": true,
      "vertx": {
        "maxWebSocketFrameSize": 200000000,
        "maxWebSocketMessageSize": 200000000,
        "tryUsePerMessageWebSocketCompression": true
      }
    }
  }
}
```