身份认证与应用安全 / 系统课时
区分过期篡改与格式错误
区分过期篡改与格式错误
JWT 校验失败不能只返回一个“解析失败”。本节把过期、签名不匹配、结构损坏和参数非法拆成可定位的结果,并用一段可运行的 JJWT 示例验证每种分支,最终形成既便于排障、又不会把敏感校验细节泄露给客户端的处理方式。
学习目标
- 能区分
ExpiredJwtException、SignatureException、MalformedJwtException与参数非法 - 能把底层异常映射成稳定的认证失败代码,而不是直接暴露异常文本
- 能用构造过期、篡改和损坏令牌的方式验证异常分类
先按失败性质分类
在 JJWT 0.13.0 中,parseSignedClaims 会在解析签名 JWT 时完成结构读取、签名验证和声明校验;签名不可信时应直接丢弃令牌。ExpiredJwtException 表示令牌已超过 exp,SignatureException 表示签名无法通过验证,MalformedJwtException 表示紧凑结构、Base64Url 内容或头部等无法按 JWT 解析。([GitHub][1])
参数非法应在进入解析器前先处理,例如 null、空字符串或只有空白字符。这样可以把“调用方没有提供令牌”和“提供了一个损坏令牌”分开,否则日志里很容易混成同一类故障。
| 情况 | 服务端分类 | 处理重点 |
|---|---|---|
| 已过期 | TOKEN_EXPIRED |
可提示重新登录或走刷新流程 |
| 签名不匹配 | SIGNATURE_INVALID |
不读取、不信任其中的 Claims |
| 结构损坏 | MALFORMED_TOKEN |
记录格式问题,不尝试修补令牌 |
| 参数为空 | INVALID_ARGUMENT |
优先检查请求头提取逻辑 |

用可运行示例制造四类失败
下面示例使用 JJWT 0.13.0。项目需要 jjwt-api,并在运行时提供 jjwt-impl 与 jjwt-jackson;这是 JJWT 官方给出的 JDK 项目依赖组合。([GitHub][1])
片段示例:将以下依赖放入现有 Maven 项目的 <dependencies> 中。
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-api</artifactId>
<version>0.13.0</version>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-impl</artifactId>
<version>0.13.0</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-jackson</artifactId>
<version>0.13.0</version>
<scope>runtime</scope>
</dependency>下面的 Java 类可以直接运行。它生成正常令牌和已过期令牌,再分别篡改 payload、传入损坏字符串和空白参数,最后打印统一的分类结果。
package com.example.jwt;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.ExpiredJwtException;
import io.jsonwebtoken.JwtException;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.MalformedJwtException;
import io.jsonwebtoken.UnsupportedJwtException;
import io.jsonwebtoken.security.SignatureException;
import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.Base64;
import java.util.Date;
public class JwtFailureClassifier {
record Result(boolean valid, String code, String subject) {}
static Result verify(SecretKey key, String token) {
if (token == null || token.isBlank()) {
return new Result(false, "INVALID_ARGUMENT", null);
}
try {
Claims claims = Jwts.parser()
.verifyWith(key)
.build()
.parseSignedClaims(token)
.getPayload();
return new Result(true, "OK", claims.getSubject());
} catch (ExpiredJwtException e) {
return new Result(false, "TOKEN_EXPIRED", null);
} catch (SignatureException e) {
return new Result(false, "SIGNATURE_INVALID", null);
} catch (MalformedJwtException e) {
return new Result(false, "MALFORMED_TOKEN", null);
} catch (UnsupportedJwtException e) {
return new Result(false, "UNSUPPORTED_TOKEN", null);
} catch (IllegalArgumentException e) {
return new Result(false, "INVALID_ARGUMENT", null);
} catch (JwtException e) {
return new Result(false, "JWT_INVALID", null);
}
}
public static void main(String[] args) {
SecretKey key = Jwts.SIG.HS256.key().build();
Instant now = Instant.now();
String valid = Jwts.builder()
.subject("alice")
.expiration(Date.from(now.plusSeconds(300)))
.signWith(key)
.compact();
String expired = Jwts.builder()
.subject("alice")
.expiration(Date.from(now.minusSeconds(30)))
.signWith(key)
.compact();
String[] parts = valid.split("\\.");
String changedPayload = Base64.getUrlEncoder()
.withoutPadding()
.encodeToString("{\"sub\":\"mallory\"}".getBytes(StandardCharsets.UTF_8));
String tampered = parts[0] + "." + changedPayload + "." + parts[2];
print("valid", verify(key, valid));
print("expired", verify(key, expired));
print("tampered", verify(key, tampered));
print("malformed", verify(key, "broken-token"));
print("blank", verify(key, " "));
}
static void print(String name, Result result) {
System.out.println(name + " -> " + result);
}
}预期输出
valid -> Result[valid=true, code=OK, subject=alice]
expired -> Result[valid=false, code=TOKEN_EXPIRED, subject=null]
tampered -> Result[valid=false, code=SIGNATURE_INVALID, subject=null]
malformed -> Result[valid=false, code=MALFORMED_TOKEN, subject=null]
blank -> Result[valid=false, code=INVALID_ARGUMENT, subject=null]不要把底层异常原样返回客户端
服务端日志可以保留分类、请求路径、追踪 ID 和必要的异常类型,但不应把完整异常堆栈、签名算法细节、密钥信息或底层异常文本直接放进响应。对客户端而言,过期通常可以返回稳定的 token_expired;其他无法信任的令牌可以统一返回 invalid_token。
把分类接到认证链
实际项目中,令牌校验器应返回受控结果或抛出项目自己的认证异常,再由 Spring Security 的认证入口统一生成 HTTP 401。这样“对外响应稳定”和“对内日志可定位”可以同时成立:客户端不需要理解 JJWT 的异常体系,运维人员仍能迅速区分过期、篡改、格式损坏和参数提取错误。