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

区分过期篡改与格式错误

区分过期篡改与格式错误

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 优先检查请求头提取逻辑

JWT 校验失败分类流程

用可运行示例制造四类失败

下面示例使用 JJWT 0.13.0。项目需要 jjwt-api,并在运行时提供 jjwt-impl 与 jjwt-jackson;这是 JJWT 官方给出的 JDK 项目依赖组合。([GitHub][1])

片段示例:将以下依赖放入现有 Maven 项目的 <dependencies> 中。

xml
<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、传入损坏字符串和空白参数,最后打印统一的分类结果。

java
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);
    }
}

预期输出

text
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 的异常体系,运维人员仍能迅速区分过期、篡改、格式损坏和参数提取错误。

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

目录与阅读设置

阅读设置

17

记录一个想法

区分过期篡改与格式错误

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

登录哪都通