WebSocket Authentication

Apache APISIX supports WebSocket traffic, but the WebSocket protocol doesn’t handle authentication. This article guides you on how to configure authentication for WebSocket connections using Apache APISIX.

WebSocket Protocol

To establish a WebSocket connection, the client sends a WebSocket handshake request, for which the server returns a WebSocket handshake response as shown below:

Client request

  1. GET /chat HTTP/1.1
  2. Host: server.example.com
  3. Upgrade: websocket
  4. Connection: Upgrade
  5. Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
  6. Sec-WebSocket-Protocol: chat, superchat
  7. Sec-WebSocket-Version: 13
  8. Origin: http://example.com

Server response

  1. HTTP/1.1 101 Switching Protocols
  2. Upgrade: websocket
  3. Connection: Upgrade
  4. Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
  5. Sec-WebSocket-Protocol: chat

The handshake workflow is shown below:

Websocket Handshake Workflow

WebSocket Authentication

APISIX supports several authentication methods like basic-auth, key-auth, and jwt-auth.

While establishing connections from the client to server in the handshake phase, APISIX first checks its authentication information before choosing to forward the request or deny it.

Prerequisites

Before you move on, make sure you have:

  1. A WebSocket server as the Upstream. This article uses Postman’s public echo service: wss://ws.postman-echo.com/raw.
  2. APISIX 3.0 installed.

Configuring Authentication

Create a Route

First we will create a Route to the Upstream echo service.

Since the Upstream uses wss protocol, the scheme is set to https. We should also set enable_websocket to true.

In this tutorial, we will use the key-auth Plugin. This would work similarly for other authentication methods:

  1. curl --location --request PUT 'http://127.0.0.1:9180/apisix/admin/routes/1' \
  2. --header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  3. --header 'Content-Type: application/json' \
  4. --data-raw '{
  5.     "uri": "/*",
  6.     "methods": ["GET"],
  7.     "enable_websocket": true,
  8.     "upstream": {
  9.         "type": "roundrobin",
  10.         "nodes": {
  11.             "ws.postman-echo.com:443": 1
  12.         },
  13.         "scheme": "https"
  14.     },
  15.     "plugins": {
  16.         "key-auth": {}
  17.     }
  18. }'

Create a Consumer

We will now create a Consumer and add a key this_is_the_key. A user would now need to use this key configured in the Consumer object to access the API.

  1. curl --location --request PUT 'http://127.0.0.1:9180/apisix/admin/consumers/jack' \
  2. --header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  3. --header 'Content-Type: application/json' \
  4. --data-raw '{
  5.     "username": "jack",
  6.     "plugins": {
  7.         "key-auth": {
  8.             "key": "this_is_the_key"
  9.         }
  10.     }
  11. }'

Testing the Route

Now, if you try to connect ws://127.0.0.1:9080/raw without the apikey header or an incorrect key, APISIX will return a 401 Unauthorized.

Connect without Key

To authenticate, you can add the header apikey with the value this_is_the_key:

Connect with key