Module bus.auth
Package org.miaixz.bus.auth.metric

Class JWT

java.lang.Object
org.miaixz.bus.auth.metric.JWT
All Implemented Interfaces:
JWTRegister<JWT>
public class JWT extends Object implements JWTRegister<JWT>
JSON Web Token (JWT) 实现类，基于 RFC 7519 标准，用于在网络应用间传递声明。
  • header：声明签名算法等信息
  • payload：承载声明和明文数据
  • signature：签名部分（JWS），确保数据完整性
Since:
Java 17+
Author:
Kimi Liu

  • Constructor Details

    • JWT

      public JWT()
      构造函数，初始化空的 JWT 对象，设置默认编码为 UTF-8。

    • JWT

      public JWT(String token)
      构造函数，初始化并解析 JWT 令牌。
      Parameters:
      token - JWT 令牌字符串

  • Method Details

    • of

      public static JWT of()
      创建空的 JWT 对象。
      Returns:
      新的 JWT 实例

    • of

      public static JWT of(String token)
      创建并解析 JWT 对象。
      Parameters:
      token - JWT 令牌字符串，格式为 xxxx.yyyy.zzzz
      Returns:
      解析后的 JWT 实例
      Throws:
      IllegalArgumentException - 如果令牌为空

    • parse

      public JWT parse(String token) throws IllegalArgumentException
      解析 JWT 令牌字符串，分解为 header、payload 和 signature 三部分。
      Parameters:
      token - JWT 令牌字符串
      Returns:
      当前 JWT 实例
      Throws:
      IllegalArgumentException - 如果令牌为空或格式不正确

    • setCharset

      public JWT setCharset(Charset charset)
      设置 JWT 使用的字符编码。
      Parameters:
      charset - 字符编码
      Returns:
      当前 JWT 实例

    • setKey

      public JWT setKey(byte[] key)
      设置签名密钥，默认使用 HS256 (HmacSHA256) 算法。
      Parameters:
      key - 签名密钥
      Returns:
      当前 JWT 实例

    • setSigner

      public JWT setSigner(String algorithmId, byte[] key)
      设置签名算法和密钥。
      Parameters:
      algorithmId - 签名算法 ID（如 HS256）
      key - 签名密钥
      Returns:
      当前 JWT 实例

    • setSigner

      public JWT setSigner(String algorithmId, Key key)
      设置签名算法和密钥。
      Parameters:
      algorithmId - 签名算法 ID（如 HS256）
      key - 签名密钥
      Returns:
      当前 JWT 实例

    • setSigner

      public JWT setSigner(String algorithmId, KeyPair keyPair)
      设置非对称签名算法和密钥对。
      Parameters:
      algorithmId - 签名算法 ID（如 RS256）
      keyPair - 密钥对
      Returns:
      当前 JWT 实例

    • setSigner

      public JWT setSigner(org.miaixz.bus.auth.metric.jwt.signature.JWTSigner signer)
      设置签名器。
      Parameters:
      signer - 签名器
      Returns:
      当前 JWT 实例

    • getSigner

      public org.miaixz.bus.auth.metric.jwt.signature.JWTSigner getSigner()
      获取签名器。
      Returns:
      当前使用的签名器

    • getHeaders

      public Map<String,Object> getHeaders()
      获取所有头部信息。
      Returns:
      头部信息的 Map

    • getHeader

      public JWTHeader getHeader()
      获取头部对象。
      Returns:
      JWTHeader 实例

    • getHeader

      public Object getHeader(String name)
      获取指定头部信息。
      Parameters:
      name - 头部字段名称
      Returns:
      头部字段值

    • getAlgorithm

      public String getAlgorithm()
      获取算法 ID（alg）头部信息。
      Returns:
      算法 ID
      See Also:

    • setHeader

      public JWT setHeader(String name, Object value)
      设置头部信息。
      Parameters:
      name - 头部字段名称
      value - 头部字段值
      Returns:
      当前 JWT 实例

    • addHeaders

      public JWT addHeaders(Map<String,?> headers)
      添加多个头部信息。
      Parameters:
      headers - 头部信息 Map
      Returns:
      当前 JWT 实例

    • getPayloads

      public Map<String,Object> getPayloads()
      获取所有载荷信息。
      Returns:
      载荷信息的 Map

    • getPayload

      public JWTPayload getPayload()
      获取载荷对象。
      Returns:
      JWTPayload 实例

    • getPayload

      public Object getPayload(String name)
      获取指定载荷信息。
      Parameters:
      name - 载荷字段名称
      Returns:
      载荷字段值

    • getPayload

      public <T> T getPayload(String propertyName, Type propertyType)
      获取指定载荷信息并转换为指定类型。
      Type Parameters:
      T - 目标类型
      Parameters:
      propertyName - 载荷字段名称
      propertyType - 目标类型
      Returns:
      转换后的载荷字段值，或 null 如果无法转换

    • setPayload

      public JWT setPayload(String name, Object value)
      设置载荷信息。
      Specified by:
      setPayload in interface JWTRegister<JWT>
      Parameters:
      name - 载荷字段名称
      value - 载荷字段值
      Returns:
      当前 JWT 实例

    • addPayloads

      public JWT addPayloads(Map<String,?> payloads)
      添加多个载荷信息。
      Parameters:
      payloads - 载荷信息 Map
      Returns:
      当前 JWT 实例

    • sign

      public String sign()
      使用默认签名器生成 JWT 字符串。
      Returns:
      JWT 字符串（header.payload.signature）

    • sign

      public String sign(org.miaixz.bus.auth.metric.jwt.signature.JWTSigner signer)
      使用指定签名器生成 JWT 字符串

      自动补充头部信息：

      • 若未定义 "alg"，根据签名器设置算法 ID
      Parameters:
      signer - 签名器
      Returns:
      JWT 字符串
      Throws:
      org.miaixz.bus.core.lang.exception.JWTException - 如果签名器为 null

    • verify

      public boolean verify()
      验证 JWT 令牌是否有效。
      Returns:
      true 如果签名有效，否则 false

    • validate

      public boolean validate(long leeway)
      验证 JWT 令牌是否有效，包括签名和时间字段检查。

      检查内容：

      • 签名是否有效
      • notBefore：生效时间不能晚于当前时间
      • expiresAt：失效时间不能早于当前时间
      • issuedAt：签发时间不能晚于当前时间
      Parameters:
      leeway - 容忍时间（秒），用于时间检查的宽松度
      Returns:
      true 如果令牌有效，否则 false

    • verify

      public boolean verify(org.miaixz.bus.auth.metric.jwt.signature.JWTSigner signer)
      使用指定签名器验证 JWT 令牌。

      如果签名器为 null 或 NoneJWTSigner，则认为 JWT 无签名，签名部分必须为空。

      Parameters:
      signer - 签名器，null 时默认为无签名
      Returns:
      true 如果签名有效，否则 false
      Throws:
      org.miaixz.bus.core.lang.exception.JWTException - 如果没有可验证的令牌

    • splitToken

      public static List<String> splitToken(String token)
      将 JWT 令牌字符串拆分为三部分（header, payload, signature）。
      Parameters:
      token - JWT 令牌字符串
      Returns:
      包含三部分的 List
      Throws:
      org.miaixz.bus.core.lang.exception.JWTException - 如果令牌格式不正确（不是三部分）