Apache APISIX WebSocket 认证配置指南

Apache APISIX WebSocket 认证配置指南

apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/gh_mirrors/ap/apisix

前言

在现代 Web 应用中，WebSocket 协议因其全双工通信能力被广泛应用于实时消息推送、在线聊天等场景。然而，WebSocket 协议本身并不提供认证机制，这给服务安全带来了挑战。本文将详细介绍如何利用 Apache APISIX 为 WebSocket 连接配置认证功能。

WebSocket 协议基础

WebSocket 连接建立过程分为握手阶段和通信阶段：

1. 握手阶段：客户端发送 HTTP 升级请求，服务器响应确认升级
2. 通信阶段：双方通过 WebSocket 协议进行全双工通信

典型握手过程如下：

客户端请求示例：

GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13

服务器响应示例：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=

APISIX 认证机制

Apache APISIX 支持多种认证插件，可无缝应用于 WebSocket 连接：

1. Basic Auth：基于用户名密码的基础认证
2. Key Auth：基于 API 密钥的简单认证
3. JWT Auth：基于 JSON Web Token 的认证

这些插件在 WebSocket 握手阶段进行验证，确保只有合法请求能建立连接。

配置实战

环境准备

1. 已安装 Apache APISIX 3.0 或更高版本
2. 准备 WebSocket 上游服务（本文使用 Postman 的公开回显服务）

步骤一：创建路由

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"
    },
    "plugins": {
        "key-auth": {}
    }
}'

关键参数说明：

• enable_websocket：启用 WebSocket 支持
• scheme: https：指定上游使用 HTTPS/WSS 协议
• key-auth 插件：启用 API 密钥认证

步骤二：创建消费者

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"
        }
    }
}'

此配置创建了一个名为 "jack" 的消费者，并分配了 API 密钥 "this_is_the_key"。

测试验证

未认证测试

直接连接 ws://127.0.0.1:9080/raw 将收到 401 Unauthorized 响应，证明认证机制生效。

认证测试

在请求头中添加正确的 API 密钥：

apikey: this_is_the_key

此时应能成功建立 WebSocket 连接并进行通信。

安全建议

1. 密钥管理：定期轮换 API 密钥，避免长期使用同一密钥
2. HTTPS 加密：生产环境务必使用 WSS(WebSocket Secure)协议
3. 访问控制：配合 limit-req 等插件防止未授权访问
4. 多因素认证：对敏感操作可结合多种认证方式

总结

通过 Apache APISIX 的认证插件，我们可以轻松为 WebSocket 服务添加安全层。这种方案具有以下优势：

1. 协议透明：对 WebSocket 客户端和服务端完全透明
2. 灵活配置：支持多种认证方式，可按需组合
3. 集中管理：统一在 API 网关层实现安全策略
4. 高性能：认证过程对通信性能影响极小

开发者可以根据实际业务需求，选择合适的认证方式保护 WebSocket 服务。

apisix The Cloud-Native API Gateway 项目地址: https://gitcode.com/gh_mirrors/ap/apisix