认证与接口安全

本文面向需要联调登录、排查 401/签名异常或配置生产安全策略的研发和运维团队。它说明三条关键后端安全链路：

• 用户如何登录
• 登录后如何续期
• 项目在 JWT 之外提供接口安全能力的原因

认证目标

商业版后端的认证目标不只是让用户完成登录，还需要同时兼顾：

• 前后端联调体验
• 会话续期体验
• 企业项目中的安全要求

因此当前项目采用的是：

• Access Token
• Refresh Token Cookie
• API 安全签名
• 接口级权限控制

登录链路

登录入口位于：

POST /api/v1/auth/signin

后端完成的事情包括：

1. 校验用户名和密码
2. 生成 Access Token
3. 生成 Refresh Token
4. 通过 HttpOnly Cookie 下发 Refresh Token

其中最值得注意的是：Refresh Token 不只是简单返回给前端，而是通过 Cookie 参与整个续期链路。

刷新令牌链路

当前端发现 Access Token 失效时，会调用：

POST /api/v1/auth/refresh

后端会：

• 校验当前 Refresh Token
• 重新签发 Access Token
• 重新写入新的 Refresh Token Cookie

如果刷新失败，会同步清理 Cookie，前端再回到登录流程。

会话管理

当前认证不是“一个人一个 token”这么简单，还支持会话管理，例如：

• 查询当前账号的会话列表
• 下线其他设备
• 下线指定会话

这类能力很适合企业实际项目里的账号安全场景。

需要登录的接口如何保护

通常会组合这些能力：

• JwtGuard
• ApiBearerAuth
• API 权限装饰器

可以按三层理解：

1. 先确认用户是否登录
2. 再确认当前接口是否允许该用户调用
3. 视情况继续叠加签名校验

API 安全签名的作用

JWT 解决的是“你是谁”，但在一些场景下还需要进一步防护请求本身。因此项目还增加了 API 安全能力，例如：

• 时间戳校验
• 随机数校验
• RSA 密钥配置
• 签名豁免路径

它更适合这些场景：

• 开放环境
• 对安全性要求更高的企业项目
• 需要防止简单重放请求的接口

前后端联调时最常见的问题

登录成功，但刷新页面后登录状态失效

优先检查：

• Refresh Token Cookie 是否成功写入
• 域名和 SameSite 策略是否正确
• HTTPS 和 Secure 设置是否匹配

已登录，但某些接口还是 401

优先检查：

• Access Token 是否过期
• 前端请求头是否正确
• 该接口是否要求 API 安全头

接口一直提示签名失败

优先检查：

• 是否启用了 API 安全
• 前端是否正确追加签名头
• 时间偏差和随机数配置是否合理

配置建议

开发环境

重点先保证登录、刷新和联调链路稳定。

生产环境

重点再进一步确认：

• Token 密钥
• Cookie 域名和 HTTPS
• 是否强制要求签名
• 是否需要会话审计

检查清单

完成认证与接口安全配置后，建议确认：

• 登录、刷新、退出和会话管理接口表现符合预期。
• Refresh Token Cookie 的 Domain、SameSite、Secure 与部署域名匹配。
• 需要登录的接口受 JWT 和权限控制保护。
• API 安全签名开关、豁免路径和密钥配置符合项目安全要求。