认证与接口安全
共享前端通过 Bearer Access Token 调用 Java 接口，并通过 Refresh Token Cookie 恢复会话。服务端使用 Sa-Token 与数据库会话有效性检查，不要求前端切换为另一种登录协议。
前端接入时先做什么
使用配套管理端时，先把代理地址指向 Java，沿用已有登录与密码加密封装。无需自行在 YAML 中添加 JWT 签名密钥，也不需要为普通业务请求额外生成 API 签名。
开发新客户端时，按下方顺序获取安全配置、公钥和登录凭证，并实现 Cookie 续期。直接在调试工具中把明文密码提交到登录接口，不能代替现有前端的加密请求。
登录和刷新链路
- 前端读取公开安全配置与 RSA 公钥，按现有密码加密协议提交登录。
- auth 校验账号和登录策略，签发令牌并创建会话。
- 响应返回 Access Token，并写入 Refresh Token Cookie。
- 前端携带 Bearer Token 请求业务；服务端检查登录、会话及相应权限。
- 刷新页面或令牌续期时，前端请求 refresh，服务端校验刷新会话并返回新的凭证。
| 入口 | 用途 |
|---|---|
/api/v1/auth/signin | 登录 |
/api/v1/auth/signup | 注册，受注册开关与校验控制 |
/api/v1/auth/captcha | 验证码 |
/api/v1/auth/refresh | 刷新令牌 |
/api/v1/user/info | 当前用户与权限信息 |
/api/v1/crypto/pubkey | RSA 公钥 |
/api/v1/crypto/security-config | 前端公开安全配置 |
登录成功不意味着会话永久有效。用户停用、删除或会话撤销后，后续请求需重新校验。IdentityWebMvcConfig 装配会话校验与 API 权限拦截器，不能只检查浏览器里是否还有 Token。
密码传输与保存
前端复用 encryptPasswordFields 处理密码字段及密钥版本头；服务端由 crypto 域解密，新密码使用 BCrypt 保存。RSA 密码加密与请求签名不是同一机制，HTTPS 上线仍然需要配置。
新密码保留 6–32 个 Java 字符约束，并要求 UTF-8 编码不超过 72 字节。不能用截断密码满足 BCrypt 的长度限制。排查特殊字符或中文密码时同时核对字符数与字节数。
生产按配置持久化 RSA 私钥，多实例必须一致；私钥不放进公开配置或日志。
Java 当前不要求请求签名
Java 公开配置当前返回 enabled: true、signatureRequired: false。共享前端 applyApiSecurityHeaders 因此跳过请求签名，仍正常携带 Bearer Token。
不要为了“补齐安全头”在前端强制生成签名，也不要把 Java 免签理解为免登录、免权限或已实现请求防重放。业务幂等和敏感操作鉴权仍需各自实现。
Refresh Cookie 与 HTTPS
Java 刷新 Cookie 使用 HttpOnly、SameSite=Lax，Secure 由 app.auth.refresh-cookie-secure 决定。本地 HTTP 开发关闭 Secure，公网 HTTPS 保持 true。
推荐同站点网关部署。跨域时须同时核对 CORS、请求凭据和 Cookie 的站点策略；仅允许 Origin 并不能绕过浏览器的跨站 Cookie 限制。不要将 Token 填入 URL 来解决普通接口鉴权问题。
登录失败策略
站点设置中的 loginMaxRetryCount > 0 时启用账号失败锁定，按数据库账号 ID 共享计数；验证码错误与不存在账号不累计已有账号的密码失败次数。锁定期内请求不续期，成功登录在签发前清理未锁定计数。
重试次数为 0 或未配置时不限制；启用而时长无效时默认 10 分钟。启用锁定后 Redis 故障返回受控错误，不退化为各节点独立计数。
排查入口
| 现象 | 先检查 |
|---|---|
| 登录 400 | 请求字段、验证码、RSA keyId 与密码规则 |
| 登录后持续 401 | Bearer Token、数据库会话、账号状态及 Redis |
| 刷新后退出 | Cookie 的 Secure/SameSite、域名、代理及刷新响应 |
| 页面可见但接口 403 | 有效角色的显式 API 授权，而非仅菜单授权 |
代码从 auth/controller/AuthController、auth/service、crypto/service、auth/security/SessionValidityInterceptor 和 access/security/ApiPermissionInterceptor 开始定位。公开路径由 admin/config/ApplicationSecurityConfig 管理，新增业务接口不能随意加入免登录名单。