SpringBoot实战：5分钟搞定Sa-Token集成WebSocket身份认证（附完整代码）

关注

VIP免费原创 2026-02-23 00:42:01 417 阅读 AI 写同款· GEO 优化 ›

使用 Sa-Token 解决 WebSocket 握手身份认证 在 WebSocket 中集成 Sa-Token 身份认证，保证连接的安全性…… 阅读详情

SpringBoot实战：5分钟搞定Sa-Token集成WebSocket身份认证（附完整代码）

最近在做一个实时协作编辑的项目，后台需要向多个客户端推送文档的实时变更。一开始直接用原生WebSocket，连接倒是很快建起来了，但马上就遇到了一个头疼的问题：我怎么知道连上来的是谁？总不能随便一个匿名用户都能连上来接收敏感数据吧。WebSocket协议本身对身份认证这块几乎是空白的，握手阶段就那么几秒钟，传统的Session、Cookie机制在这里都不太好使。

折腾了一圈，试过在连接参数里传用户ID，也试过建立连接后再发个认证消息，总觉得不够优雅，安全上也有漏洞。直到把Sa-Token这个权限框架引入进来，才发现原来WebSocket的身份认证可以做得这么简洁。今天我就把自己踩坑后总结出来的最佳实践分享给你，核心目标就是让你在5分钟内，给SpringBoot项目中的WebSocket加上一套可靠的身份认证机制。

无论你是要做IM聊天、订单状态推送、还是实时数据大屏，这套方案都能直接复用。我会提供两种主流的集成方式：基于javax.websocket的原生方案和Spring封装的WebSocketHandler方案，并附上完整的、可运行的代码。咱们不搞理论堆砌，直接上手实操。

1. 为什么WebSocket需要独立的身份认证？

你可能已经习惯了在HTTP请求里用@PreAuthorize注解或者拦截器来做权限控制，但WebSocket是另一套玩法。它的连接建立过程（握手）虽然基于HTTP，但一旦握手成功，就升级成了全双工的TCP长连接，后续的通信不再走HTTP的那套请求-响应模型。这意味着，那些依赖HTTP Header、Cookie的认证方案，在WebSocket通道里可能就失效了或者变得很别扭。

更关键的是安全风险。想象一下，如果你的实时股票报价WebSocket服务没有认证，攻击者可以轻易建立连接，耗尽服务器资源；或者，一个普通用户连接上了只应向管理员推送的报警通道。因此，在握手阶段完成身份核验，是保障WebSocket服务安全的第一道，也是最重要的一道防线。

Sa-Token在这里扮演的角色，就是一个统一的会话管理中心。它帮我们解决了两个核心问题：

令牌（Token）的传递与验证：如何在WebSocket握手请求中携带并验证代表用户身份的令牌。
会话（Session）的绑定：如何将成功的WebSocket连接与后台的用户会话对象关联起来，以便后续的定向消息推送。

下面的表格对比了WebSocket认证的几种常见思路，你可以看看为什么Sa-Token的方案更优：

认证方式	实现复杂度	安全性	与现有系统集成度	推荐场景
连接参数传ID	极低	极低	低	内部测试、无需安全要求的场景
连接后首次消息认证	中	中	中	客户端可控性强、允许短暂未认证连接的场景
自定义握手协议	高	高	中	对协议有定制化需求的项目
Sa-Token令牌认证	低	高	高	绝大多数SpringBoot项目，尤其是已有Sa-Token登录体系的

提示：如果你的项目已经用Sa-Token管理了HTTP登录，那么为WebSocket增加认证几乎是零成本的，因为用户会话是共享的。

2. 项目初始化与依赖配置

我们先从一个干净的SpringBoot项目开始。这里假设你使用Maven进行构建。打开你的pom.xml文件，确保引入了以下三个核心依赖：

<dependencies>
    <!-- SpringBoot Web基础 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- SpringBoot WebSocket支持 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-websocket</artifactId>
    </dependency>

    <!-- Sa-Token 权限认证框架 -->
    <dependency>
        <groupId>cn.dev33</groupId>
        <artifactId>sa-token-spring-boot-starter</artifactId>
        <version>1.34.0</version> <!-- 请使用最新稳定版 -->
    </dependency>
</dependencies>

版本注意：Sa-Token的版本更新较快，建议通过Maven中央仓库查询最新版本。1.34.0版本在WebSocket集成方面做了不少优化。

接下来，我们需要一个简单的用户登录接口，用于在前端获取连接WebSocket所必需的Token。这个控制器同时服务于你的HTTP API和WebSocket认证。