身份认证与应用安全 / 系统课时
用刷新接口换新访问令牌
用刷新接口换新访问令牌
刷新接口的目标不是重新执行一次登录,而是在 Refresh Token 仍然有效时签发新的短期 Access Token。本节实现校验、签发和错误边界,并区分哪些失败必须让客户端结束当前登录。
学习目标
- 按服务端状态校验 Refresh Token 后签发新的 Access Token
- 统一处理过期、撤销、未知令牌等认证失败
- 区分“登录已失效”和“服务暂时不可用”两类错误
刷新流程只做续期
客户端在 Access Token 临近过期或收到约定的未授权响应后,向 /api/auth/refresh 提交 Refresh Token。服务端不需要再次验证密码,而是根据 Refresh Token 的摘要查状态记录,通过后再签发新的 Access Token。

在服务端完成统一校验
下面是片段示例,假定 RefreshTokenStore 能按原始令牌查出服务端状态,AccessTokenIssuer 封装实际 JWT 签发逻辑。接口对“未知、已撤销、已过期”统一返回 401,避免向客户端泄露过多内部状态。
package com.example.auth;
import java.time.Duration;
import java.time.Instant;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;
@Service
public class RefreshService {
private static final Duration ACCESS_TOKEN_TTL = Duration.ofMinutes(15);
private final RefreshTokenStore refreshTokenStore;
private final AccessTokenIssuer accessTokenIssuer;
public RefreshService(
RefreshTokenStore refreshTokenStore,
AccessTokenIssuer accessTokenIssuer
) {
this.refreshTokenStore = refreshTokenStore;
this.accessTokenIssuer = accessTokenIssuer;
}
public RefreshResponse refresh(String rawRefreshToken) {
if (rawRefreshToken == null || rawRefreshToken.isBlank()) {
throw unauthorized();
}
RefreshTokenState state = refreshTokenStore.find(rawRefreshToken)
.orElseThrow(this::unauthorized);
Instant now = Instant.now();
if (state.revokedAt() != null || !state.expiresAt().isAfter(now)) {
throw unauthorized();
}
String accessToken = accessTokenIssuer.issue(
state.userId(),
ACCESS_TOKEN_TTL
);
return new RefreshResponse(
accessToken,
"Bearer",
ACCESS_TOKEN_TTL.toSeconds()
);
}
private ResponseStatusException unauthorized() {
return new ResponseStatusException(
HttpStatus.UNAUTHORIZED,
"refresh token is invalid"
);
}
}如果系统还维护用户禁用状态、密码版本或安全版本号,应在签发前一并检查;检测到账号已被禁用或安全版本失效时,应撤销相关 Refresh Token,并让当前登录结束,而不是继续发新 Access Token。
暴露一个最小刷新接口
控制器只接收 Refresh Token 并把校验交给服务层,避免在 Web 层重复写状态判断。下面仍是片段示例,依赖上一节中的 RefreshService。
package com.example.auth;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/auth")
public class RefreshController {
private final RefreshService refreshService;
public RefreshController(RefreshService refreshService) {
this.refreshService = refreshService;
}
@PostMapping("/refresh")
public RefreshResponse refresh(@RequestBody RefreshRequest request) {
return refreshService.refresh(request.refreshToken());
}
}
record RefreshRequest(String refreshToken) {
}
record RefreshResponse(String accessToken, String tokenType, long expiresIn) {
}这里示例只返回新的 Access Token,没有自动轮换 Refresh Token。如果项目采用 Refresh Token Rotation,应在同一事务中让旧令牌失效并写入新令牌,避免两个长期有效令牌同时存活。
用请求验证成功路径
假定应用监听端口为 <PORT>,且 <REFRESH_TOKEN> 对应一条未撤销、未过期的服务端记录,可以直接调用刷新接口:
curl -i -X POST "http://localhost:<PORT>/api/auth/refresh" \
-H "Content-Type: application/json" \
-d '{"refreshToken":"<REFRESH_TOKEN>"}'预期输出:
HTTP/1.1 200
Content-Type: application/json
{"accessToken":"<ACCESS_TOKEN>","tokenType":"Bearer","expiresIn":900}<PORT> 与 <ACCESS_TOKEN> 的实际值会因本地配置和签发结果不同。示例把 Access Token 有效期固定为 15 分钟,所以 expiresIn 为 900 秒。
哪些失败必须结束登录
| 情况 | 服务端响应 | 客户端处理 |
|---|---|---|
| Refresh Token 不存在 | 401 | 清除本地 Access/Refresh Token,回到登录页 |
| Refresh Token 已撤销 | 401 | 清除当前登录态,不再重试刷新 |
| Refresh Token 已过期 | 401 | 清除当前登录态,要求重新登录 |
| 用户被禁用或安全版本失效 | 401 或项目约定的认证失败状态 | 清除登录态,并停止自动刷新 |
| 数据库、缓存或认证服务暂时不可用 | 503 | 保留登录态,按退避策略稍后重试 |
关键区别是:401 表示这枚凭证已经不能证明登录身份,继续重试没有意义;503 表示服务端暂时无法完成判断,客户端不应把一次基础设施故障误当成“用户已经退出”。
刷新接口稳定后,前端只需要把 Access Token 的短生命周期与 Refresh Token 的长生命周期分开处理:前者频繁替换,后者一旦被服务端判定失效,就必须终止当前会话并重新登录。