身份认证与应用安全 / 系统课时

用刷新接口换新访问令牌

用刷新接口换新访问令牌

刷新接口的目标不是重新执行一次登录,而是在 Refresh Token 仍然有效时签发新的短期 Access Token。本节实现校验、签发和错误边界,并区分哪些失败必须让客户端结束当前登录。

学习目标

  • 按服务端状态校验 Refresh Token 后签发新的 Access Token
  • 统一处理过期、撤销、未知令牌等认证失败
  • 区分“登录已失效”和“服务暂时不可用”两类错误

刷新流程只做续期

客户端在 Access Token 临近过期或收到约定的未授权响应后,向 /api/auth/refresh 提交 Refresh Token。服务端不需要再次验证密码,而是根据 Refresh Token 的摘要查状态记录,通过后再签发新的 Access Token。

Refresh Token 换取新 Access Token 的时序与失败分支

在服务端完成统一校验

下面是片段示例,假定 RefreshTokenStore 能按原始令牌查出服务端状态,AccessTokenIssuer 封装实际 JWT 签发逻辑。接口对“未知、已撤销、已过期”统一返回 401,避免向客户端泄露过多内部状态。

java
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。

java
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> 对应一条未撤销、未过期的服务端记录,可以直接调用刷新接口:

bash
curl -i -X POST "http://localhost:<PORT>/api/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"<REFRESH_TOKEN>"}'

预期输出:

text
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 的长生命周期分开处理:前者频繁替换,后者一旦被服务端判定失效,就必须终止当前会话并重新登录。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用刷新接口换新访问令牌

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通