📚 课程目录第3章 JWT令牌生命周期

3. JWT令牌生命周期：签发时间(iat)、过期时间(exp)、生效时间(nbf)字段详解

JWT 的生命周期由三个核心时间戳字段共同定义：签发时间（iat）、过期时间（exp）和生效时间（nbf）。这三个字段构成了令牌从诞生到失效的完整时间轴，是后端进行安全合规校验的基础。理解它们的语义、校验逻辑和常见陷阱，是构建可靠认证系统的关键。

3.1 字段定义与语义

这三个字段均遵循 RFC 7519 标准，使用 NumericDate 格式（Unix 时间戳，即自 1970-01-01 00:00:00 UTC 以来的秒数）。

字段	全称	语义	校验规则	常见用途
`iat`	Issued At	令牌的签发时间	可选校验，通常用于记录或计算令牌年龄	日志审计、令牌年龄计算、刷新策略
`exp`	Expiration Time	令牌的过期时间	必须校验：当前时间 > `exp` 时，令牌无效	强制令牌失效，限制会话时长
`nbf`	Not Before	令牌的生效时间	可选校验：当前时间 < `nbf` 时，令牌尚未生效	延迟生效、定时任务授权、预签发令牌

关键原则： exp 是强制校验字段，iat 和 nbf 为可选字段。但为了安全合规，建议后端服务至少校验 exp，并根据业务场景决定是否校验 nbf。

3.2 生命周期时间轴与校验逻辑

下图展示了 JWT 从签发到失效的完整时间轴，以及后端校验引擎在每个时间点的判定逻辑。

3.3 字段使用规范与避坑指南

3.3.1 签发时间（iat）

用途：记录令牌的签发时刻，用于日志审计、计算令牌已使用时长、判断是否需要刷新。
避坑：不要依赖 iat 做安全校验，因为签发时间本身不决定令牌是否有效。攻击者可以篡改 iat 为过去时间，但无法绕过 exp 校验。
建议：在刷新令牌策略中，通常要求新令牌的 iat 必须晚于旧令牌的 iat，防止重放攻击。

3.3.2 过期时间（exp）

强制校验：所有后端服务必须校验 exp，拒绝已过期的令牌。
时钟偏差（Clock Skew）：分布式系统中，服务器时间可能存在微小差异。建议在校验时允许 30~60 秒的宽容窗口，避免因时间不同步导致合法令牌被误判。
常见错误：将 exp 设置为 0 或负数，导致令牌立即过期；或将 exp 设置为字符串而非数字，导致解析失败。

  安全合规要求：根据 OAuth 2.0 安全最佳实践，访问令牌（Access Token）的 exp 建议设置为 15 分钟以内；刷新令牌（Refresh Token）可根据业务需求设置为 7 天、30 天或更长，但必须配合刷新策略和撤销机制。

3.3.3 生效时间（nbf）

用途：用于延迟生效场景，例如：预签发一个将在未来某个时间点生效的授权令牌；定时任务中，提前生成令牌但限制其只能在特定时间段内使用。
校验逻辑：如果当前时间早于 nbf，则令牌被视为“尚未生效”，后端应返回 401 Unauthorized 或自定义错误码。
避坑：如果业务不需要延迟生效，建议在签发令牌时省略 nbf 字段，避免因时钟偏差导致令牌在生效前被误用。

3.4 典型错误码断言与故障排查

当 JWT 生命周期校验失败时，后端应返回明确的错误码，帮助客户端和运维人员快速定位问题。下表列出了常见的错误场景及对应的错误码断言。

错误场景	错误码	错误描述	排查方向
令牌已过期	`401` / `TOKEN_EXPIRED`	当前时间 > `exp`	检查客户端时间是否同步；检查令牌签发时的 `exp` 值是否合理
令牌尚未生效	`401` / `TOKEN_NOT_YET_VALID`	当前时间 < `nbf`	检查服务器时间是否准确；检查 `nbf` 是否被错误设置
签发时间异常	`400` / `INVALID_IAT`	`iat` 格式错误或为未来时间	检查令牌生成逻辑；确保 `iat` 使用正确的 Unix 时间戳
时钟偏差导致误判	`401` / `TOKEN_EXPIRED`	实际未过期，但因服务器时间差异被拒绝	启用时钟偏差宽容窗口；同步 NTP 时间

3.5 代码示例：Java 后端校验逻辑

以下示例展示了使用 io.jsonwebtoken（JJWT）库进行生命周期校验的典型实现，包含时钟偏差处理。

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.ExpiredJwtException;
import io.jsonwebtoken.security.SignatureException;
import java.time.Instant;
import java.util.Date;

public class JwtValidator {

    private static final long CLOCK_SKEW_SECONDS = 60; // 允许 60 秒时钟偏差

    public static Claims validateToken(String token, String secretKey) {
        try {
            return Jwts.parserBuilder()
                    .setSigningKey(secretKey)
                    .setAllowedClockSkewSeconds(CLOCK_SKEW_SECONDS) // 设置时钟偏差
                    .build()
                    .parseClaimsJws(token)
                    .getBody();
        } catch (ExpiredJwtException e) {
            // 令牌已过期，返回 TOKEN_EXPIRED 错误码
            throw new SecurityException("TOKEN_EXPIRED: Token has expired at " + e.getClaims().getExpiration());
        } catch (SignatureException e) {
            // 签名无效
            throw new SecurityException("INVALID_SIGNATURE: Token signature is invalid");
        } catch (Exception e) {
            // 其他解析错误（如格式错误、nbf 校验失败等）
            throw new SecurityException("INVALID_TOKEN: " + e.getMessage());
        }
    }

    // 手动校验 nbf 示例（如果库未自动校验）
    public static void checkNotBefore(Claims claims) {
        Date nbf = claims.getNotBefore();
        if (nbf != null && nbf.after(new Date())) {
            throw new SecurityException("TOKEN_NOT_YET_VALID: Token is not valid until " + nbf);
        }
    }
}

重要提示：在生产环境中，不要将 CLOCK_SKEW_SECONDS 设置过大（如超过 5 分钟），否则会削弱 exp 的安全作用。建议根据实际部署环境的 NTP 同步精度，设置为 30~120 秒。

3.6 生命周期字段的合规性检查清单

在安全审计或代码审查中，可以使用以下清单快速评估 JWT 生命周期管理的合规性：

是否强制校验 exp？ —— 所有受保护端点必须校验。
是否设置了合理的时钟偏差？ —— 建议 30~60 秒。
是否在不需要时省略了 nbf？ —— 避免不必要的校验复杂性。
错误码是否明确区分“过期”和“未生效”？ —— 便于客户端差异化处理。
日志中是否记录了 iat、exp 和 nbf 的值？ —— 用于故障排查和审计。
刷新令牌时是否校验了新旧 iat 的先后顺序？ —— 防止重放攻击。

通过严格遵循上述规范，可以有效避免因 JWT 生命周期管理不当导致的安全漏洞和故障，确保后端认证系统的健壮性与合规性。