116 lines
2.8 KiB
Markdown
116 lines
2.8 KiB
Markdown
# 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. **设备列表管理**：可查看在线设备并强制下线
|
||
|