1 IM 系统鉴权与 Token 安全规范文档

西街长安 edited this page 2026-01-30 21:37:11 +08:00

Unescape Escape

Table of Contents

• IM 系统鉴权与 Token 安全规范文档
• 1. 概述
• 2. 鉴权方式选择
• 3. Token 生成规则
• 3.1 Token 内容结构（JWT 示例）
• 3.2 Token 生成流程
• 4. Token 使用
• 4.1 HTTP 接口鉴权
• 4.2 WebSocket 鉴权
• 5. Token 过期策略
• 5.1 Token 刷新流程
• 6. 多端登录处理

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

IM 系统鉴权与 Token 安全规范文档

1. 概述

本规范用于确保系统用户身份验证、消息安全和多端同步安全。 鉴权体系采用 Token（JWT 或自定义） + HTTPS/WebSocket 方式。

---

2. 鉴权方式选择

方法
JWT（JSON Web Token）+ Redis黑名单机制

---

3. Token 生成规则

3.1 Token 内容结构（JWT 示例）

{
  "userId": 1001,            // 用户ID
  "iat": 1700000000,         // 签发时间（Unix时间戳）
  "exp": 1700003600,         // 过期时间
  "deviceId": "uuid-xxxx",   // 设备ID，用于多端区分
  "role": "user"             // 角色
}

• 签名算法：HMAC-SHA256 或 RSA
• 签名秘钥：服务端统一管理，不暴露给客户端

---

3.2 Token 生成流程

1. 用户登录（用户名/密码）
2. 验证用户名与密码正确
3. 生成 Token，写入 Redis（可选）
4. 返回 Token 给客户端

响应示例：

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

---

4. Token 使用

4.1 HTTP 接口鉴权

• 客户端请求带上 Header：

Authorization: Bearer <token>

• 后端解析 Token：
  1. 校验签名
  2. 校验 exp 是否过期
  3. 校验 Redis 黑名单（可选）
• 不通过返回 401 / code 1006

---

4.2 WebSocket 鉴权

• 建立连接时通过 Query 或 Header 传 Token：

ws://example.com/ws?token=xxxx&deviceId=uuid-001

• 握手阶段：
  1. 服务器验证 Token
  2. 成功返回 AUTH_SUCCESS
  3. 失败返回 AUTH_FAIL 并关闭连接

---

5. Token 过期策略

类型	建议值	说明
短期 Token	30 分钟 ~ 1 小时	防止长时间泄露
长期 Refresh Token	7 ~ 30 天	用于获取新 Token，安全性高
WebSocket 长连接	Token 与短期有效期一致	客户端定期刷新 Token（心跳或重连时验证）

5.1 Token 刷新流程

1. 客户端 Token 快过期时，调用刷新接口
2. 服务端验证 Refresh Token
3. 返回新 Token，更新 Redis / 黑名单

---

6. 多端登录处理

• 每个设备对应一个 deviceId
• Token 中绑定 deviceId
• 多端策略：
  1. 允许多端同时登录：每端单独维护 Token
  2. 限制单端登录：新登录覆盖旧设备 Token
  3. 设备列表管理：可查看在线设备并强制下线