Class JWTDecoder

java.lang.Object
tech.riemann.nif.auth.jwt.JWTDecoder
public class JWTDecoder extends Object
JWT解码器

用于解析和验证JWT（JSON Web Token）令牌

主要功能： 1. 验证JWT签名的有效性（verify方法） 2. 获取JWT的Payload信息（verifiedPayload方法） 3. 获取JWT的Subject（主题）信息 4. 支持多种签名算法（RSA、EC、EdDSA等）

安全警告： - subject()方法不会验证签名，可能被伪造，不能用于身份认证 - 应该使用verifiedSubject()方法获取经过验证的Subject - 在进行任何权限判断前，必须先调用verify()验证Token

使用示例： 

// 正确：验证后使用
if (decoder.verify(token)) {
    String subject = decoder.verifiedSubject(token);
    // 使用subject进行业务逻辑
}

// ❌ 错误：直接使用未验证的subject
String subject = decoder.subject(token); // 危险！
Author:
Kerbores(kerbores@riemann.tech)

  • Constructor Details

    • JWTDecoder

      public JWTDecoder(com.nimbusds.jose.jwk.JWK jwk, String keyId)
      兼容构造器：仅指定密钥与密钥ID，时钟容差使用默认值（60 秒）
      Parameters:
      jwk - 用于验证JWT签名的JSON Web Key
      keyId - 密钥ID

  • Method Details

    • key

      public Key key(com.nimbusds.jose.JWSAlgorithm jwsAlgorithm)
      根据JWS算法获取对应的公钥

      支持三种算法类型： 1. RSA算法 - 返回RSA公钥 2. EC算法 - 返回EC公钥 3. EdDSA算法 - 返回OctetKeyPair公钥

      Parameters:
      jwsAlgorithm - JWS签名算法
      Returns:
      对应的公钥
      Throws:
      IllegalArgumentException - 如果算法不支持

    • verify

      public boolean verify(String token)
      验证Token的签名与有效期

      使用默认时钟容差（clockSkewSeconds）进行校验

      Parameters:
      token - JWT Token字符串
      Returns:
      true表示签名有效且在有效期内，false表示签名无效或已过期/未生效

    • verify

      public boolean verify(String token, long clockSkewSeconds)
      验证Token的签名与有效期

      校验规则： 1. 签名必须有效 2. exp 缺失直接拒绝（防止"永不过期"的 Token） 3. 当前时间不能超过 exp（允许 clockSkewSeconds 秒的时钟偏差） 4. 当前时间不能早于 nbf（未生效的 Token 拒绝） 5. 当前时间不能早于 iat（签发时间在未来的 Token 拒绝）

      格式非法/验签失败的 Token 统一返回 false（不抛异常），与 JwksJWTGenerator#verify 行为一致

      Parameters:
      token - JWT Token字符串
      clockSkewSeconds - 允许的时钟偏差（秒），0 表示不允许偏差
      Returns:
      true表示签名有效且在有效期内，false表示无效（含格式非法/签名无效/过期/未生效）

    • isValidTimeClaims

      public boolean isValidTimeClaims(com.nimbusds.jwt.JWTClaimsSet claims, long clockSkewSeconds)
      校验 JWT 声明中的有效期（exp / iat / nbf）

      校验规则： 1. exp 缺失直接拒绝（防止"永不过期"的 Token） 2. 当前时间不能超过 exp（允许 clockSkewSeconds 秒的时钟偏差） 3. 当前时间不能早于 nbf（未生效的 Token 拒绝） 4. 当前时间不能早于 iat（签发时间在未来的 Token 拒绝；iat 缺失放行，为可选声明）

      供子类（如 JwksJWTGenerator）在自定义验签逻辑后复用，保证有效期校验单一来源

      Parameters:
      claims - JWT 声明集
      clockSkewSeconds - 允许的时钟偏差（秒），0 表示不允许偏差
      Returns:
      true 表示处于有效期内

    • verifiedPayload

      public com.nimbusds.jose.Payload verifiedPayload(String token)
      获取验证后的Payload信息

      先验证签名与有效期，验证通过后返回Payload；格式非法/验证失败返回null（不抛异常）

      Parameters:
      token - JWT Token字符串
      Returns:
      验证通过的Payload，如果验证失败返回null

    • subject

      public String subject(String token)
      获取JWT的主题(Subject)信息

      安全警告: 此方法仅解析JWT的Payload部分并提取Subject字段，不会验证JWT签名的有效性。 这意味着:

      • 攻击者可以伪造任意JWT token，此方法仍会返回伪造的Subject
      • 过期的、被篡改的、无效的token都能被此方法解析
      • 绝对不能将此方法返回的Subject用于身份认证或权限判断

      适用场景:

      • 日志记录：记录请求的token信息用于审计
      • 调试分析：查看token内容但不做信任决策
      • 配合其他验证机制：在已有其他安全验证的情况下使用

      不适用场景:

      推荐做法: 

      // 正确：使用验证后的subject
String subject = decoder.verifiedSubject(token);
if (subject != null) {
    // 使用subject进行业务逻辑
}

// ❌ 错误：直接使用未验证的subject
String subject = decoder.subject(token); // 危险！可能被伪造
      Parameters:
      token - JWT token字符串
      Returns:
      Subject字段值，如果token格式错误则抛出异常
      Throws:
      RuntimeException - 当token格式不正确时抛出
      See Also:

    • verifiedSubject

      public String verifiedSubject(String token)
      验证并获取主题

      先验证Token签名，验证通过后才返回Subject 这是安全的获取Subject的方法

      Parameters:
      token - JWT Token字符串
      Returns:
      验证通过后的Subject，如果验证失败返回null