Overview
This document is to introduce how to demo Websocket capabilities within CA API Gateway v9.0, step-by-step.
Introduction
Websocket is a protocol providing full-duplex communication channels over a single TCP connection. It can transmit voice call, video call, and text messages. Websocket is a very efficient protocol overall. However, due to the nature of the protocol itself, attacks such as Cross-Site WebSocket Hijacking can easily happen if you don’t have proper authentication and authorization in place. The protocol (RFC 6455 - The WebSocket protocol ) itself doesn’t specify/recommend any client authentication, so there will be a very good fit for our solution if the customer concerns security around websocket.
CA API Gateway integrates WebSockets out-of-box. In version 9.0 and prior, the Websocket is part of MAG, and starting from 9.1, the WebSocket module is part of Enterprise Gateway or core Gateway. The Gateway proxy WebSockets connection and perform message filtering. Threat protection and OAuth can be enforced within Connection/Inbound Policy, request parameters/headers can be extracted and build outbound URL dynamically with the help of a technical assertion. Here is the conceptual diagram
WebSocket Testing Client
- Chrome Extension: Simple WebSocket Client
WebSocket Testing Server
- Public Websocket echo instance: ws://echo.websocket.org:80/
- Install and configure Websocket Testing Suite: Autobahn|Testsuite — AutobahnTestsuite 0.6.1 documentation
To start Autobahn ws server, I use: #sudo wstest -m echoserver -w ws://localhost:9001 -d
Gateway Setup Step-by-Step
1. Download the tactical websocket assertion from filter2: Smb://filer2.l7tech.com/departments/Dev/Tactical/Distribution/Modular Assertions/WebSocketAssertion
The oob WebSocket assertion doesn't support dynamic outbound URL and compression. If you don't have such requirement, you could skip step 1,2,3. And you will not need the Autobahn ws server neither.
2. Upload this assertion to the gateway.
3. Replace the oob WebSocket Assertion, and restart the gateway. here are commands:
# service ssg stop
# cd /opt/SecureSpan/Gateway/runtime/modules/assertions
# mv WebSocketAssertion-9.0.00.aar WebSocketAssertion-9.0.00.aar.org
# cp /home/ssgconfig/WebSocketAssertion-9.0.00.xxxxx.aar WebSocketAssertion-9.0.00.aar
# shown layer7@layer7 WebSocketAssertion-9.0.00.aar
# chmod a-x-w+r WebSocketAssertion-9.0.00.aar
# service ssg start
4. Logon the policy manager and create a policy folder "WebSocket"
5. Import the 3 attached policies:
Policy Name | EndPoint
| Policy |
---|
Connection Handler | /wsconnect | Websocket-wsconnect.xml |
Inbound Handler | /wsinbound | Websocket-wsinbound.xml |
Outbound Handler | /wsoutbound | Websocket-wsoutbound.xml |
6. Configure Websocket Connection Properties as followings:
Here I assume we will use public echo instance for testing. If you have autobahn websocket server installed and configured on your laptop, then you could proxy your autobahn instances, just set the outbound URL in the 2nd screenshot to ws://hostname:9001
Run the Demo
I usually run the following 4 demos, but of course you could always add more.
Proxy WebSocket using Simple Public Echo Instance: ws://explore.apim.ca:8081
OAuth: ws://explore.apim.ca:8081/?access_token=xxxxxxx
OAuth + dynamic URL using Autobahn: ws://explore.apim.ca:8081/chat/mychat?access_token=xxxxxxx
Message filtering: