You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/12/06 08:07:05 UTC
[apisix] 01/01: docs: added websocket authentication
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch docs/tutorial-websocket-authentication
in repository https://gitbox.apache.org/repos/asf/apisix.git
commit d0dbcca8e977d470aa3642530fda448d2bf8e3c9
Author: 琚致远 <ju...@apache.org>
AuthorDate: Tue Dec 6 16:06:44 2022 +0800
docs: added websocket authentication
---
.../latest/tutorials/websocket-authentication.md | 143 +++++++++++++++++++++
1 file changed, 143 insertions(+)
diff --git a/docs/en/latest/tutorials/websocket-authentication.md b/docs/en/latest/tutorials/websocket-authentication.md
new file mode 100644
index 000000000..51c3ea43d
--- /dev/null
+++ b/docs/en/latest/tutorials/websocket-authentication.md
@@ -0,0 +1,143 @@
+---
+title: WebSocket Authentication
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - WebSocket
+ - Authentication
+description: This article guides you on how to configure authentication for WebSocket connections.
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+Apache APISIX supports [WebSocket](https://en.wikipedia.org/wiki/WebSocket) traffic, but the WebSocket protocal doesn't handle authentication. This artical guides you on how to configure authentication for WebSocket connections.
+
+## WebSocket Protocal
+
+To establish a WebSocket connection, the client sends a WebSocket **handshake** request, for which the server returns a WebSocket handshake response, see below:
+
+**Client Request**
+
+```text
+GET /chat HTTP/1.1
+Host: server.example.com
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
+Sec-WebSocket-Protocol: chat, superchat
+Sec-WebSocket-Version: 13
+Origin: http://example.com
+```
+
+**Server Response**
+
+```text
+HTTP/1.1 101 Switching Protocols
+Upgrade: websocket
+Connection: Upgrade
+Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
+Sec-WebSocket-Protocol: chat
+```
+
+**Handshake Workflow**
+
+
+
+## WebSocket Authentication
+
+Apache APISIX supports several ways to do authentication, for example: `basic-auth`, `key-auth`, `jwt-auth`, and so on.
+
+When establishing one connection from Client to Server, in the **handshake** phase, APISIX first checks its authentication information, then chooses to proxy this request or deny it directly.
+
+### Pre-requisite
+
+1. One WebSocket server as the Upstream server. In this article, let's use [Postman's Public Echo Service](https://blog.postman.com/introducing-postman-websocket-echo-service/): `wss://ws.postman-echo.com/raw`.
+2. APISIX 3.0 Installed.
+
+:::note
+
+APISIX 3.0 and APISIX 2.x are using different Admin API endpoint. Please check [APISIX 3.0 Deployment Modes](https://apisix.apache.org/docs/apisix/deployment-modes/).
+
+:::
+
+### Key Auth
+
+#### Create one Route
+
+:::tip
+In this article, when using Apache APISIX 3.0:
+
+1. The Upstream server is using `wss` protocal, so we should set `scheme` as `https` in the `upstream` block.
+2. Set `enable_websocket` as `true`.
+:::
+
+```sh
+curl --location --request PUT 'http://127.0.0.1:9180/apisix/admin/routes/1' \
+--header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "uri": "/*",
+ "methods": ["GET"],
+ "enable_websocket": true,
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "ws.postman-echo.com:443": 1
+ },
+ "scheme": "https"
+ }
+}'
+```
+
+#### Create one Consumer
+
+```sh
+curl --location --request PUT 'http://127.0.0.1:9180/apisix/admin/consumers/jack' \
+--header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "username": "jack",
+ "plugins": {
+ "key-auth": {
+ "key": "this_is_the_key"
+ }
+ }
+}'
+```
+
+#### Connect without Key
+
+Connect `ws://127.0.0.1:9080/raw` without `key`, APISIX returns `401 Unauthorized` status code.
+
+
+
+#### Connect with Key
+
+Connect `ws://127.0.0.1:9080/raw` with `key`, it's successfully.
+
+
+
+### Note
+
+Other authentication methods are similar to this one.
+
+## Reference
+
+1. [Wikipedia - WebSocket](https://en.wikipedia.org/wiki/WebSocket)
\ No newline at end of file