JWT学习（二）之JWT + Refresh Token 接口规范

JWT + Refresh Token 接口规范

1. 规范概述

1.1 设计目标

• 使用 JWT 作为 Access Token
• 使用 Refresh Token 刷新 Access Token
• Access Token 无状态、短有效期
• Refresh Token 服务端可控、一次性使用
• 支持踢人、禁用、审计
• 符合 OAuth2.0 / OAuth2.1 设计思想

1.2 Token 类型说明

1.3 签名算法

• JWT 签名算法：RS256
• 私钥：仅认证服务
• 公钥：网关 / 业务服务

2. JWT Claim 规范（强制）

2.1 Access Token Claim 定义

{
"iss": "kms-auth",
"aud": "kms-api",
"sub": "user_123",
"jti": "550e8400-e29b-41d4",
"iat": 1769750000,
"exp": 1769751800,
"scope": "user admin"
}

⚠️ JWT 中禁止存储任何敏感信息

3. 通用接口规范

3.1 请求头规范

Content-Type: application/json
Authorization: Bearer <access_token>

3.2 统一响应格式

{
"code": 0,
"message": "success",
"data": {}
}

3.3 错误码定义

4. 接口定义（核心）

4.1 获取 Access Token & Refresh Token（登录）

接口描述

• 用户登录认证
• 使用 HTTP Basic 校验客户端身份
• 使用 Form 表单提交参数

接口定义

POST /oauth/token

客户端认证方式（强制）

Authorization: Basic base64(client_id:client_secret)

请求格式

Content-Type: application/x-www-form-urlencoded

请求参数（password 模式）

grant_type=password
&username=zhangsan
&password=123456
&scope=user

参数说明

响应示例（JSON）

{
"code": 0,
"message": "success",
"data": {
"access_token": "eyJhbGciOiJSUzI1NiIs…",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "f8a7c9b0-xxxx",
"scope": "user"
}
}

4.2 使用 Refresh Token 刷新 Access Token

接口描述

• Access Token 过期后调用
• Refresh Token 仅可使用一次

接口定义

POST /oauth/token

客户端认证（必须）

Authorization: Basic base64(client_id:client_secret)

请求格式

Content-Type: application/x-www-form-urlencoded

请求参数（refresh_token 模式）

grant_type=refresh_token
&refresh_token=f8a7c9b0-xxxx

响应示例

{
"code": 0,
"data": {
"access_token": "new-jwt-token",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "new-refresh-token"
}
}

强制安全规则

• ✅ Refresh Token 一次性使用
• ✅ 返回 新的 Refresh Token
• ❌ 旧 Refresh Token 立即作废
• ❌ Refresh Token 不允许并发使用

4.3 用户登出（Token 主动失效）

接口描述

• 主动退出登录
• 支持踢人

接口定义

POST /oauth/logout

请求头

Authorization: Bearer <access_token>

服务端处理逻辑

• 删除 Refresh Token
• 将 Access Token 的 jti 加入黑名单（Redis）

响应示例

{
"code": 0,
"message": "logout success"
}

4.4 Token 校验接口（可选）

接口定义

POST /oauth/introspect

请求参数

{
"token": "access_token"
}

响应示例

{
"active": true,
"sub": "user_123",
"exp": 1769751800,
"scope": "user"
}

5. Refresh Token 存储规范（生产级）

5.1 Redis 存储示例

key: refresh_token:{hash}
{
"userId": "user_123",
"clientId": "kms-web",
"expireAt": 1772352000,
"status": "ACTIVE"
}

安全要求

• 仅存 Hash
• 设置 TTL
• 支持状态禁用

6. 安全控制（必须）

6.1 Access Token 校验

• 验签（RS256）
• 校验 exp
• 校验 iss / aud
• 校验 jti 黑名单

6.2 客户端安全

• client_secret 不允许下发前端
• HTTPS 强制
• Token 禁止出现在 URL

6.3 Refresh Token 风控

• 一次性使用
• 绑定 client_id
• 可选：IP / UA 校验

7. 常见异常示例

Token 过期

{
"code": 40102,
"message": "access token expired"
}

Refresh Token 无效

{
"code": 40103,
"message": "refresh token invalid"
}

8. 一句话总结

Access Token 使用 JWT 实现无状态鉴权； Refresh Token 通过服务端控制保证安全； Basic + Form 保证客户端认证与参数安全传输。