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

处理刷新失败与重新登录

处理刷新失败与重新登录

刷新接口失败时,客户端不能把所有 401 都当成“再刷新一次”,否则容易形成循环请求;服务端也不应把用户被禁用、令牌撤销等内部细节全部暴露给前端。本节建立一个稳定的失败契约,让客户端明确区分“可重试”和“必须重新登录”。

学习目标

  • 区分 Access Token 失效、Refresh Token 不可用和临时服务故障
  • 设计不会无限刷新或无限重试的前后端处理流程
  • 在需要重新认证时可靠清理会话并回到登录页

先把失败分成两类

刷新失败最重要的不是给每个内部原因设计不同页面,而是判断当前会话还有没有恢复可能。

Refresh Token 过期、被撤销、被检测到重放、签名无效,或者用户状态已经不允许继续登录,都属于不可恢复的当前会话。服务端可以在日志中保留具体原因,但对客户端统一返回 401 和稳定错误码 REAUTH_REQUIRED。数据库暂时不可用、下游密钥服务超时等短暂故障则更适合返回 503,客户端可以有限重试,而不应立即清空登录状态。

刷新失败后的客户端决策流程

服务端给前端稳定的错误契约

在 Spring Boot 中,可以把具体异常收敛成少量外部错误码。下面是片段示例,假设这些刷新异常已经由认证服务抛出;处理器只负责把它们映射成稳定响应。

java
@RestControllerAdvice
public class AuthExceptionHandler {

    @ExceptionHandler({
            ExpiredRefreshTokenException.class,
            InvalidRefreshTokenException.class,
            RevokedRefreshTokenException.class,
            RefreshTokenReuseException.class,
            UserNotAllowedException.class
    })
    ResponseEntity<AuthError> handleReauthRequired(RuntimeException ex) {
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                .body(new AuthError("REAUTH_REQUIRED", "Login again"));
    }

    public record AuthError(String code, String message) {
    }
}

这段代码依赖项目中的自定义异常,不能脱离当前 Spring Boot 工程独立运行。它的目的不是隐藏服务端日志,而是让前端只依赖一个长期稳定的状态:收到 401 + REAUTH_REQUIRED 就结束当前登录会话,不再继续尝试刷新。

如果是数据库连接失败或认证服务暂时不可用,不要伪装成 REAUTH_REQUIRED。这类故障应返回 503 Service Unavailable,否则客户端会把一个临时故障误判成用户必须重新登录。

客户端只允许一次刷新链

前端遇到业务接口的 Access Token 过期后,应发起一次刷新。多个并发请求同时失败时,最好复用同一个刷新 Promise,而不是每个请求都提交一次 Refresh Token;这样也能避免轮换机制把并发刷新误判为旧令牌重放。

下面示例假设 Refresh Token 放在 HttpOnly Cookie 中,因此 JavaScript 不读取它,只对刷新接口启用 credentials: "include"。

ts
let accessToken: string | null = null;
let refreshInFlight: Promise<boolean> | null = null;

async function refreshOnce(): Promise<boolean> {
  if (!refreshInFlight) {
    refreshInFlight = fetch("/auth/refresh", {
      method: "POST",
      credentials: "include"
    })
      .then(async (response) => {
        if (response.ok) {
          const body = await response.json();
          accessToken = body.accessToken;
          return true;
        }

        if (response.status === 401) {
          const body = await response.json();
          if (body.code === "REAUTH_REQUIRED") {
            accessToken = null;
            return false;
          }
        }

        throw new Error(`refresh failed: ${response.status}`);
      })
      .finally(() => {
        refreshInFlight = null;
      });
  }

  return refreshInFlight;
}

页面可见效果是:同一时刻即使多个 API 都因 Access Token 过期返回 401,也只会产生一个刷新请求;刷新成功后,调用方可以重试原请求;刷新返回 REAUTH_REQUIRED 时统一进入退出登录流程。

验证必须重新登录的响应

可以直接用一个已经过期或已撤销的 Refresh Token 验证服务端契约:

bash
curl -i -X POST "https://<HOST>:<PORT>/auth/refresh" --cookie "refresh_token=<EXPIRED_OR_REVOKED_REFRESH_TOKEN>"

预期结果:

text
HTTP/1.1 401
Content-Type: application/json

{"code":"REAUTH_REQUIRED","message":"Login again"}

客户端收到这个响应后,应停止刷新、清除内存中的 Access Token 和用户状态,并跳转登录页。如果 Refresh Token 使用 HttpOnly Cookie,还应由服务端在注销或失败处理接口中发送过期的 Set-Cookie 来清除该 Cookie,前端不要尝试用 JavaScript 删除它。

避免三种常见循环

第一种循环是“业务 API 401 → 刷新 401 → 再刷新”,解决方法是把刷新接口排除在自动刷新拦截器之外。第二种是“刷新 503 → 永久重试”,应限制次数并使用退避。第三种是多个并发 401 同时刷新,必须用单飞机制合并请求。

重新登录不是异常兜底的最后一句话,而是认证状态机中的明确终点:只要刷新凭证已经不可恢复,就结束当前会话;只有真正的临时服务故障才允许有限重试。

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

目录与阅读设置

阅读设置

17

记录一个想法

处理刷新失败与重新登录

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

登录哪都通