【Java系列】Hutool-JWT

温馨提示：本文 hutool 版本 大于 5.7.0

一、什么是 JWT

Json web token (JWT)，是为了在网络应用环境间传递声明而执行的一种基于JSON的开放标准（RFC 7519)。该 token 被设计为紧凑且安全的，特别适用于分布式站点的单点登录（SSO）场景。JWT 的声明一般被用来在身份提供者和服务提供者间传递被认证的用户身份信息，以便于从资源服务器获取资源，也可以增加一些额外的其它业务逻辑所必须的声明信息，该 token 也可直接被用于认证，也可被加密。

二、JWT 长什么样？

JWT 是由三段信息构成的，将这三段信息文本用 . 链接在一起就构成了JWT 字符串。就像这样：

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyWkRJS2hsR0NXYlhrNjdXZERvV1B3QmN3SnoiLCJleHAiOjE3MDkxOTg4NDYsIm5iZiI6MTcwOTE5NzA0MX0.UlqqAPZF1VUoRLgYO8VD4wKB81oEKS2Ipz1RDVec4nM

三、JWT 的构成

第一部分我们称它为头部（header)，第二部分我们称其为载荷（payload，类似于飞机上承载的物品)，第三部分是签证（signature)。

3.1 header

JWT 的头部承载两部分信息：

• 声明类型，这里是 JWT
• 声明加密的算法 通常直接使用 HMAC SHA256

完整的头部就像下面这样的 JSON：

{
  'typ': 'JWT',
  'alg': 'HS256'
}

然后将头部进行 base64 加密（该加密是可以对称解密的)，构成了第一部分。

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

3.2 playload

载荷就是存放有效信息的地方。这个名字像是特指飞机上承载的货品，这些有效信息包含三个部分：

• 标准中注册的声明
• 公共的声明
• 私有的声明

标准中注册的声明 (建议但不强制使用)：

• iss: JWT 签发者
• sub: JWT 所面向的用户
• aud: 接收 JWT 的一方
• exp: JWT 的过期时间，这个过期时间必须要大于签发时间
• nbf: 定义在什么时间之前，该 JWT 都是不可用的
• iat: JWT 的签发时间
• jti: JWT 的唯一身份标识，主要用来作为一次性 token,从而回避重放攻击。

公共的声明：
公共的声明可以添加任何的信息，一般添加用户的相关信息或其他业务需要的必要信息。但不建议添加敏感信息，因为该部分在客户端可解密。

私有的声明：
私有声明是提供者和消费者所共同定义的声明，一般不建议存放敏感信息，因为 base64 是对称解密的，意味着该部分信息可以归类为明文信息。

定义一个 payload：

{
  "iss": "ak",
  "exp": "Thu Feb 29 19:41:25 CST 2024",
  "nbf": "Thu Feb 29 19:11:20 CST 2024"
}

然后将其进行 base64 加密，得到 JWT 的第二部分。

eyJpc3MiOiIyWkRJS2hsR0NXYlhrNjdXZERvV1B3QmN3SnoiLCJleHAiOjE3MDkxOTg4NDYsIm5iZiI6MTcwOTE5NzA0MX0

3.3 signature

JWT 的第三部分是一个签证信息，这个签证信息由三部分组成：

• header (base64 后的)
• payload (base64 后的)
• secret

这个部分需要 base64 加密后的 header 和 base64 加密后的 payload 使用 . 连接组成的字符串，然后通过 header 中声明的加密方式进行加盐 secret 组合加密，然后就构成了 JWT 的第三部分。

// javascript
var encodedString = base64UrlEncode(header) + '.' + base64UrlEncode(payload);

var signature = HMACSHA256(encodedString, 'secret'); // UlqqAPZF1VUoRLgYO8VD4wKB81oEKS2Ipz1RDVec4nM

将这三部分用 . 连接成一个完整的字符串，构成了最终的 JWT：

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyWkRJS2hsR0NXYlhrNjdXZERvV1B3QmN3SnoiLCJleHAiOjE3MDkxOTg4NDYsIm5iZiI6MTcwOTE5NzA0MX0.UlqqAPZF1VUoRLgYO8VD4wKB81oEKS2Ipz1RDVec4nM

注意：secret 是保存在服务器端的，它就是你服务端的私钥，在任何场景都不应该流露出去。一旦客户端得知这个 secret, 那就意味着客户端是可以自我签发 JWT 了。

四、如何应用

一般是在请求头里加入 Authorization，并加上 Bearer 标注：

fetch('api/user/1', {
  headers: {
    'Authorization': 'Bearer ' + token
  }
})

服务端会验证 token，如果验证通过就会返回相应的资源。

五、Hutool-JWT 使用

5.1 JWT 生成

1. HS265(HmacSHA256) 算法

public class JWTTest {

    static String ak = "2ZDIKhlGCWbXk67WdDoWPwBcwJz"; // 填写您的ak
    static String sk = "xxxxxx"; // 填写您的sk

    public static void main(String[] args) {
        String token = sign(ak, sk);
        System.out.println(token); // 打印生成的API_TOKEN
    }
    static String sign(String ak,String sk) {
        try {
            Date expiredAt = new Date(System.currentTimeMillis() + 1800*1000);
            Date notBefore = new Date(System.currentTimeMillis() - 5*1000);
            byte[] key = sk.getBytes();
            return JWT.create()
                    .setKey(key)
                    .setPayload("iss", ak)
                    .setPayload("exp", expiredAt)
                    .setPayload("nbf", notBefore)
                    .sign();
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }

}

输出内容为：eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIyWkRJS2hsR0NXYlhrNjdXZERvV1B3QmN3SnoiLCJleHAiOjE3MDkyMDY4ODUsIm5iZiI6MTcwOTIwNTA4MH0.AmQxbpLRuMxoR3bM9Lbvavs6CBxCNt5x3GHqQo2SLAc

2. 不签名 JWT

// eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwiYWRtaW4iOnRydWUsIm5hbWUiOiJsb29seSJ9.
String token = JWT.create()
	.setPayload("sub", "1234567890")
	.setPayload("name", "looly")
	.setPayload("admin", true)
	.setSigner(JWTSignerUtil.none())
	.sign();

5.2 JWT 解析

String rightToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9." +
	"eyJzdWIiOiIxMjM0NTY3ODkwIiwiYWRtaW4iOnRydWUsIm5hbWUiOiJsb29seSJ9." +
	"536690902d931d857d2f47d337ec81048ee09a8e71866bcc8404edbbcbf4cc40";

JWT jwt = JWT.of(rightToken);

// JWT
jwt.getHeader(JWTHeader.TYPE);
// HS256
jwt.getHeader(JWTHeader.ALGORITHM);

// 1234567890
jwt.getPayload("sub");
// looly
jwt.getPayload("name");
// true
jwt.getPayload("admin");

5.3 JWT 验证

1. 验证签名

String rightToken = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9." +
	"eyJzdWIiOiIxMjM0NTY3ODkwIiwiYWRtaW4iOnRydWUsIm5hbWUiOiJsb29seSJ9." +
	"536690902d931d857d2f47d337ec81048ee09a8e71866bcc8404edbbcbf4cc40";

// 密钥
byte[] key = "1234567890".getBytes();

// 默认验证HS265的算法
JWT.of(rightToken).setKey(key).verify()

2. 验证 Token

使用方法如下：

String token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJNb0xpIiwiZXhwIjoxNjI0OTU4MDk0NTI4LCJpYXQiOjE2MjQ5NTgwMzQ1MjAsInVzZXIiOiJ1c2VyIn0.L0uB38p9sZrivbmP0VlDe--j_11YUXTu3TfHhfQhRKc";

byte[] key = "1234567890".getBytes();
boolean validate = JWT.of(token).setKey(key).validate(0);

3. 验证算法

算法的验证包括两个方面

1. 验证 header 中算法 ID 和提供的算法 ID 是否一致
2. 调用 JWT.verify 验证 token 是否正确

// 创建JWT Token
final String token = JWT.create()
	.setNotBefore(DateUtil.date())
	.setKey("123456".getBytes())
	.sign();

// 验证算法
JWTValidator.of(token).validateAlgorithm(JWTSignerUtil.hs256("123456".getBytes()));

4. 验证时间

对于时间类载荷，有单独的验证方法，主要包括：

• 生效时间（JWTPayload#NOT_BEFORE）不能晚于当前时间
• 失效时间（JWTPayload#EXPIRES_AT）不能早于当前时间
• 签发时间（JWTPayload#ISSUED_AT）不能晚于当前时间

一般时间线是：

(签发时间)---------(生效时间)---------(当前时间)---------(失效时间)

签发时间和生效时间一般没有前后要求，都早于当前时间即可。

final String token = JWT.create()
	// 设置签发时间
	.setIssuedAt(DateUtil.date())
	.setKey("123456".getBytes())
	.sign();

// 由于只定义了签发时间，因此只检查签发时间
JWTValidator.of(token).validateDate(DateUtil.date());

六、小结

使用 JWT 的优势：

• 因为 json 的通用性，所以 JWT 是可以进行跨语言支持的，像 JAVA, JavaScript, NodeJS, Go 等很多语言都可以使用。
• 因为有了 payload 部分，所以 JWT 可以在自身存储一些其他业务逻辑所必要的非敏感信息。
• 便于传输，JWT 的构成非常简单，字节占用很小，所以它是非常便于传输的。
• 它不需要在服务端保存会话信息, 所以它易于应用的扩展。