Hutool JWT 基础使用

由来

从 Hutool 5.7.0 版本开始，提供了零依赖的 JWT（JSON Web Token）实现，简化了网络身份认证和信息交换的流程。本节将详细介绍 Hutool 提供的 JWT 功能，包含生成、解析和验证等操作。

JWT 结构与概念

JWT 主要由三部分组成：

1. Header（头部信息）：声明了 JWT 的签名算法和类型等信息。
2. Payload（载荷信息）：主要用于承载声明，并传递数据，这些数据是明文的。
3. Signature（签名）：用于校验数据完整性，确保数据未被篡改。

整体结构为：header.payload.signature

示例结构

header.payload.signature

Hutool JWT 模块核心类

1. JWT 类：用于链式生成、解析或验证 JWT。
2. JWTUtil 类：工具类，提供简化的 JWT 生成、解析和验证功能。

JWT 生成方法详解

1. 使用 HS256 (HmacSHA256) 算法生成 JWT

import cn.hutool.jwt.JWT;
import cn.hutool.jwt.JWTUtil;

public class JwtExample {
    public static void main(String[] args) {
        // 密钥，用于签名，HS256 算法需要提供一个 byte[] 类型的密钥
        byte[] key = "1234567890".getBytes();

        // 生成 JWT，设置载荷内容并签名
        String token = JWT.create()
            // 设置载荷，存放自定义数据
            .setPayload("sub", "1234567890")
            .setPayload("name", "looly")
            .setPayload("admin", true)
            // 设置签名的密钥
            .setKey(key)
            // 签名并生成 JWT 字符串
            .sign();

        // 打印生成的 JWT
        System.out.println("Generated Token: " + token);
    }
}

关键点解析：

• setPayload：设置 JWT 载荷，传递业务数据，如用户信息、权限标识等。可以添加任意键值对。
• setKey：设置签名密钥，HS256 算法必须提供该密钥。
• sign：执行签名操作，生成最终的 JWT。

2. 使用其他算法生成 JWT (如 RSA256)

import cn.hutool.jwt.JWT;
import cn.hutool.jwt.signers.JWTSigner;
import cn.hutool.jwt.signers.JWTSignerUtil;
import cn.hutool.crypto.KeyUtil;
import cn.hutool.crypto.SecureUtil;

import java.security.KeyPair;

public class JwtExample {
    public static void main(String[] args) {
        // 定义算法 ID
        String algorithmId = "RS256";
        
        // 生成密钥对
        KeyPair keyPair = KeyUtil.generateKeyPair(algorithmId);
        
        // 创建 RSA 签名器
        JWTSigner signer = JWTSignerUtil.createSigner(algorithmId, keyPair);

        // 生成 JWT，设置载荷内容并签名
        String token = JWT.create()
            .setPayload("sub", "1234567890")
            .setPayload("name", "looly")
            .setPayload("admin", true)
            // 设置签名器，使用 RSA256 签名
            .setSigner(signer)
            .sign();

        // 打印生成的 JWT
        System.out.println("Generated Token: " + token);
    }
}

关键点解析：

• JWTSignerUtil.createSigner：根据算法 ID 生成指定算法的签名器（如 RSA256）。
• setSigner：使用自定义签名器代替默认的 HS256 签名。

3. 生成不带签名的 JWT

import cn.hutool.jwt.JWT;
import cn.hutool.jwt.signers.JWTSignerUtil;

public class JwtExample {
    public static void main(String[] args) {
        // 生成不带签名的 JWT
        String token = JWT.create()
            .setPayload("sub", "1234567890")
            .setPayload("name", "looly")
            .setPayload("admin", true)
            // 使用 none 签名器，表示不签名
            .setSigner(JWTSignerUtil.none())
            .sign();

        // 打印生成的 JWT
        System.out.println("Generated Token: " + token);
    }
}

关键点解析：

• 使用 JWTSignerUtil.none() 可以生成不带签名的 JWT，适用于不需要签名验证的场景。

JWT 解析与获取载荷信息

import cn.hutool.jwt.JWT;

public class JwtExample {
    public static void main(String[] args) {
        // 待解析的 JWT 字符串
        String token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9." +
            "eyJzdWIiOiIxMjM0NTY3ODkwIiwiYWRtaW4iOnRydWUsIm5hbWUiOiJsb29seSJ9." +
            "536690902d931d857d2f47d337ec81048ee09a8e71866bcc8404edbbcbf4cc40";

        // 解析 JWT
        JWT jwt = JWT.of(token);

        // 获取 Header 信息
        String type = jwt.getHeader("typ"); // JWT
        String algorithm = jwt.getHeader("alg"); // HS256

        // 获取 Payload 信息
        String subject = jwt.getPayload("sub"); // 1234567890
        String name = jwt.getPayload("name"); // looly
        Boolean isAdmin = jwt.getPayload("admin"); // true

        // 打印解析结果
        System.out.println("Type: " + type);
        System.out.println("Algorithm: " + algorithm);
        System.out.println("Subject: " + subject);
        System.out.println("Name: " + name);
        System.out.println("Is Admin: " + isAdmin);
    }
}

关键点解析：

• JWT.of(token)：解析 JWT 字符串，获取 JWT 对象。
• getHeader 和 getPayload：分别获取 Header 和 Payload 中的信息。

JWT 验证

1. 验证签名

import cn.hutool.jwt.JWT;

public class JwtExample {
    public static void main(String[] args) {
        // 待验证的 JWT
        String token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9." +
            "eyJzdWIiOiIxMjM0NTY3ODkwIiwiYWRtaW4iOnRydWUsIm5hbWUiOiJsb29seSJ9." +
            "536690902d931d857d2f47d337ec81048ee09a8e71866bcc8404edbbcbf4cc40";

        // 密钥，用于验证签名
        byte[] key = "1234567890".getBytes();

        // 验证签名，验证通过返回 true
        boolean isValid = JWT.of(token).setKey(key).verify();
        System.out.println("Is Valid: " + isValid);
    }
}

2. 详细验证

import cn.hutool.jwt.JWT;

public class JwtExample {
    public static void main(String[] args) {
        // 待验证的 JWT
        String token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJNb0xpIiwiZXhwIjoxNjI0OTU4MDk0NTI4LCJpYXQiOjE2MjQ5NTgwMzQ1MjAsInVzZXIiOiJ1c2VyIn0.L0uB38p9sZrivbmP0VlDe--j_11YUXTu3TfHhfQhRKc";

        // 密钥，用于验证签名
        byte[] key = "1234567890".getBytes();

        // 验证 Token 的详细信息，0 表示不容忍时间偏差
        boolean isValid = JWT.of(token).setKey(key).validate(0);
        System.out.println("Is Valid: " + isValid);
    }
}

关键点解析：

• verify()：验证签名的有效性。
• validate(int tolerance)：更详细的验证，包括生效时间、失效时间、签发时间等。

总结

Hutool 提供的 JWT 功能使得开发人员可以更轻松地集成 JWT 身份认证，无论是生成、解析还是验证，都提供了简洁的 API。开发时需特别关注密钥、签名算法及载荷信息的管理，以确保安全性和数据完整性。