IM/docs/IM 系统鉴权与 Token 安全规范文档.md

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. 设备列表管理：可查看在线设备并强制下线