Proxying WebSocket Traffic

Set up AM:

1. (For AM 6.5.x and earlier versions) Select  Identities > demo, and set the demo user password to Ch4ng31t.

2. (For AM 6.5.3 and later versions) Select  Services > Add a Service, and add a Validation Service with the following Valid goto URL Resources:

   • http://openig.example.com:8080/*

   • http://openig.example.com:8080/*?*

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

   • Agent ID: ig_agent

   • Password: password

   Leave all other values as default.

   See how to set up an agent in AM 6.5.2 and earlier versions.

   1. Select Applications > Agents > Java (or J2EE).

   2. Add an agent with the following values:

      • Agent ID: ig_agent

      • Agent URL: http://openig.example.com:8080/agentapp

      • Server URL: http://openam.example.com:8088/openam

      • Password: password

   3. On the Global tab, deselect Agent Configuration Change Notification.

      This option stops IG from being notified about agent configuration changes in AM, because they are not required by IG.

Set up IG:

1. Set an environment variable for the IG agent password, and then restart IG:

   $ export AGENT_SECRET_ID='cGFzc3dvcmQ='

   The password is retrieved by a SystemAndEnvSecretStore, and must be base64-encoded.

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

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

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

   {
     "name" : "sampleapp_resources",
     "baseURI" : "http://app.example.com:8081",
     "condition": "${matches(request.uri.path,'^/css')}",
     "handler": "ReverseProxyHandler"
   }

3. Add the following route to IG:

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

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

   {
     "name": "websocket",
     "baseURI": "http://app.example.com:8081",
     "condition": "${matches(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://openam.example.com:8088/openam/",
           "version": "7"
         }
       },
       {
         "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".

   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.

Test the setup:

1. If you are logged in to AM, log out.

2. Go to http://openig.example.com:8080/websocket.

   The SingleSignOnFilter redirects the request to AM for authentication.

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

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