JWT 认证指南

MLiev IAM 使用 JWT（JSON Web Token）进行 API 认证。本文档说明认证流程和 Token 管理。

认证流程

客户端                              IAM 服务
  |                                    |
  |  1. POST /api/admin/auth/login     |
  |  {"username":"admin","password":""}|
  |----------------------------------->|
  |                                    |
  |  2. 返回 accessToken + refreshToken|
  |<-----------------------------------|
  |                                    |
  |  3. 请求 API（携带 accessToken）     |
  |  Authorization: Bearer <token>     |
  |----------------------------------->|
  |                                    |
  |  4. Token 过期后，使用 refreshToken  |
  |  POST /api/admin/auth/refresh      |
  |----------------------------------->|
  |                                    |
  |  5. 返回新的 accessToken            |
  |<-----------------------------------|

管理员认证

登录

curl -X POST http://localhost:8080/api/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

响应：

{
  "code": 200,
  "message": "登录成功",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 86400
  }
}

使用 Token

在后续所有需要认证的请求中，将 accessToken 放在 Authorization 头部：

curl http://localhost:8080/api/admin/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

刷新 Token

当 accessToken 过期时，使用 refreshToken 获取新的 Token：

curl -X POST http://localhost:8080/api/admin/auth/refresh \
  -H "Authorization: Bearer <当前Token>" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "eyJhbGciOiJIUzI1NiIs..."}'

退出登录

curl -X POST http://localhost:8080/api/admin/auth/logout \
  -H "Authorization: Bearer <accessToken>"

普通用户认证

普通用户使用独立的认证端点：

操作	端点
登录	POST /api/user/login
退出	POST /api/auth/logout
刷新	POST /api/auth/refresh

Token 结构

JWT Token 的 Payload 包含以下声明（Claims）：

字段	说明
user_id	用户 ID
username	用户名
role	用户角色
exp	过期时间（Unix 时间戳）
iat	签发时间

认证中间件

系统提供三种认证中间件，用于不同场景：

中间件	说明
AuthMiddleware	要求有效 Token，否则返回 401
AdminAuthMiddleware	要求有效 Token 且角色为 admin
OptionalAuthMiddleware	Token 可选，有效时提取用户信息

配置

在 config.yaml 中配置 JWT 参数：

jwt:
  secret: "至少32字符的随机字符串"
  expire_hours: 24  # Token 过期时间（小时）

安全提示：生产环境请使用足够长度的随机字符串作为 JWT Secret，不要使用默认值。