随着实时通信需求的迅猛增长，WebSocket成为现代Web应用中不可或缺的技术之一。FastAPI作为一个高性能的Python框架，内置了对WebSocket的支持，极大地方便了开发者实现实时功能。然而，在实际应用中，为WebSocket添加安全认证却并非易事，其中涉及浏览器限制、协议处理等多方面的复杂问题。本文将深入解析如何在FastAPI中优雅地实现WebSocket认证，帮助开发者打造更加安全的实时通信应用。 首先，要明确WebSocket在认证上的特殊性。与传统HTTP请求不同，浏览器在初始化WebSocket连接时不允许开发者直接设置自定义的认证头，例如Authorization头。
这一限制来源于浏览器厂商对安全性的考量，防止滥用或信息泄露。因此，我们无法像普通API请求那样，通过Headers传递Token完成认证。这就迫使开发者寻找替代方案，以保证认证信息能在WebSocket握手阶段传递并验证。 在众多方案中，较为实用且被社区认可的做法是利用Sec-WebSocket-Protocol这个标准化的握手头来传递认证Token。Sec-WebSocket-Protocol原本用来指定子协议，这个Header接受一个字符串数组，服务器与客户端通过协商使用特定的子协议。由于这个Header可以被WebSocket握手接受并传递，选择将认证信息编码后放入该Header，成为一种有效的“变通”方法。
具体到实现，是将Bearer Token使用Base64编码后，作为Sec-WebSocket-Protocol协议名的一部分发出。 例如，在前端JavaScript代码中建立WebSocket连接时，可以这样写： let ws = new WebSocket( "ws://" + location.host + "/ws", ["yourprotocol", "base64.websocket.bearer." + B64_TOKEN] ); 这里，yourprotocol是开发者自定义的子协议标识，而base64.websocket.bearer.开头的协议字符串后面紧跟着经过Base64编码的Token。这种方式巧妙地将认证信息和子协议融合，绕开了浏览器不允许自定义Authorization Header的限制。 接下来，在服务端FastAPI实现中，需要对握手请求的Sec-WebSocket-Protocol进行拆解并解析Token。为此，一个高效的方案是创建ASGI中间件，用来拦截并处理WebSocket请求的Header，将Base64编码的Token解码并重写到Headers中的Authorization字段，以便后续基于Bearer Token的认证逻辑正常生效。 该中间件的核心流程包括获取请求中的Sec-WebSocket-Protocol Header，将其拆解为若干子协议协议标识，匹配以自定义前缀（例如base64.websocket.bearer.）开头的部分，提取出Base64编码字符串并进行解码，将解码后的Token转换成Authorization Header加到请求中，保证后续的认证流程可以直接使用。
由于这一处理发生在WebSocket握手阶段，认证信息得以在连接建立前传递与验证，大大提升了安全性。 服务端示例代码体现了上述逻辑，定义了一个WebSocketProtocolBearerMiddleware类，构造函数接收目标应用实例及Token和协议相关前缀，调用时对scope的Headers部分遍历分析与替换。注意，这种中间件的插入顺序尤为重要，应置于任何其它需要读取Authorization Header的认证中间件之前，确保有效拦截并正确注入Token。 而在实际的WebSocket路由处理函数中，也需指定认可的子协议名称，配合客户端发起连接时所用的一致，确保服务器能接受并完成握手。 例如 @router.websocket("/your-endpoint/ws") async def websocket_endpoint(websocket: WebSocket, your_auth: Depends(get_your_auth)): await websocket.accept(subprotocol='yourprotocol') # 连接建立后的业务逻辑 这里的your_auth是借助FastAPI依赖注入系统实现的认证依赖，它既支持普通HTTP请求也能兼顾WebSocket连接验证逻辑，可以访问到经过前述中间件处理且注入的Authorization Header，从而提取与验证用户身份信息。 此外，为了兼容依赖注入中鉴权函数既支持Request又支持WebSocket，可以设计认证依赖函数形如 async def get_auth_credentials(request: Request = None, websocket: WebSocket = None) -> YourAuthCredentials | None: # 根据传入参数类型判断并处理认证逻辑 这也解决了FastAPI对复杂依赖类型推断的限制，需要使用类型忽略的标记保证正常运行。
通过上述方法，不仅能保证认证信息在WebSocket连接期间安全传递，还能很好地融合FastAPI已有的认证体系，对于需要基于Token的安全WebSocket通信的应用，尤其适用。例如实现实时数据推送、在线协作应用、游戏后端服务等，安全性没有妥协，且开发体验顺畅。 总结来看，FastAPI内置支持WebSocket功能非常强大，但浏览器限制导致的认证头不可用成为直接使用Bearer Token认证的阻碍。采用Sec-WebSocket-Protocol头传递Base64编码Token的方案，配合ASGI中间件预处理Header，成为公认实用有效的实践。同时配合依赖注入机制设计适配Request与WebSocket的认证依赖函数，保证端到端身份验证严密且高效。希望本文的讲解和示例能为开发者在FastAPI中实现安全可靠的WebSocket认证提供清晰路径与实用参考，推动更多实时应用的顺畅开发与创新。
。
