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 类型说明

Token 类型	用途	有效期	存储
Access Token (JWT)	API 访问鉴权	10~30 分钟	客户端
Refresh Token	刷新 Token	7~30 天	客户端 + 服务端

1.3 签名算法

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

2. JWT Claim 规范（强制）

2.1 Access Token Claim 定义

json 复制代码

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

Claim	必填	说明
iss	是	签发方
aud	是	接收方
sub	是	用户 ID
jti	是	Token 唯一标识
iat	是	签发时间
exp	是	过期时间
scope	否	权限范围

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

3. 通用接口规范

3.1 请求头规范

http 复制代码

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

3.2 统一响应格式

json 复制代码

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

3.3 错误码定义

code	含义
0	成功
40001	请求参数错误
40101	未认证
40102	Token 过期
40103	Token 无效
40301	权限不足
50000	系统异常

4. 接口定义（核心）

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

接口描述

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

接口定义

复制代码

POST /oauth/token

客户端认证方式（强制）

http 复制代码

Authorization: Basic base64(client_id:client_secret)

请求格式

http 复制代码

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

请求参数（password 模式）

复制代码

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

参数说明

参数	必填	说明
grant_type	是	固定为 `password`
username	是	登录账号
password	是	登录密码
scope	否	权限范围

响应示例（JSON）

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

客户端认证（必须）

http 复制代码

Authorization: Basic base64(client_id:client_secret)

请求格式

http 复制代码

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

请求参数（refresh_token 模式）

复制代码

grant_type=refresh_token
&refresh_token=f8a7c9b0-xxxx

响应示例

json 复制代码

{
  "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

请求头

http 复制代码

Authorization: Bearer <access_token>

服务端处理逻辑

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

响应示例

json 复制代码

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

4.4 Token 校验接口（可选）

接口定义

复制代码

POST /oauth/introspect

请求参数

json 复制代码

{
  "token": "access_token"
}

响应示例

json 复制代码

{
  "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 过期

json 复制代码

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

Refresh Token 无效

json 复制代码

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

8. 一句话总结

Access Token 使用 JWT 实现无状态鉴权；

Refresh Token 通过服务端控制保证安全；

Basic + Form 保证客户端认证与参数安全传输。