java

关注公众号 jb51net

关闭
首页 > 软件编程 > java > jwt原理及Java实现

jwt原理及Java中实现过程

作者：༒࿈༙྇洞察༙༙྇྇࿈༒

JWT是无状态认证的JSON令牌,包含头部、载荷和签名,用于身份验证与权限管理,需注意设置过期时间、使用非对称算法、安全存储传输,及合理刷新策略,确保系统安全与效率

一、JWT 是什么？解决什么问题？


JWT（JSON Web Token）是一种把“认证信息（Claims）+ 完整性校验”打包成 自包含 的字符串的规范。

它主要用于无状态认证：服务端验证签名即可信任其中的身份与权限，无需每次查库或维护会话（session）。

但请记住：JWT 只保证 完整性（没被篡改），默认不保密（除非用 JWE 加密）。敏感信息不要塞进未加密的 JWT。

二、JWT 的结构与签名流程

JWT 的字符串形如：<header>.<payload>.<signature>

Header（JSON，Base64URL）

Payload/Claims（JSON，Base64URL）

常见注册声明：

Signature

JWS vs JWE：

三、JWT 使用流程（最小闭环）

  1. 登录：用户名密码校验成功 → 颁发短期 Access Token（JWT）+ 较长期 Refresh Token（不可见给前端或放 HttpOnly Cookie）。
  2. 访问 API：前端将 Authorization: Bearer <jwt> 送给后端。
  3. 后端：验证签名、校验 exp/nbf/aud/iss 等 → 放行。
  4. 刷新：Access Token 过期，用 Refresh Token 换新（做轮换与失效控制）。
  5. 登出/撤销（可选）：把 jti 或 refresh 的标识加入黑名单，或进行密钥轮换。

四、常见安全陷阱（一定要看）

五、Java 手写（JJWT）创建与验证

1) 依赖（Maven）

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-api</artifactId>
  <version>0.11.5</version>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-impl</artifactId>
  <version>0.11.5</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-jackson</artifactId>
  <version>0.11.5</version> <!-- for JSON serialization -->
  <scope>runtime</scope>
</dependency>

若用 RSA/EC/EdDSA：还需对应的 jjwt-xxx 或者用 java.security 生成密钥。

2) 生成密钥（示例：RSA 与 Ed25519）

// RSA 2048（推荐生产至少 2048）
KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA");
kpg.initialize(2048);
KeyPair rsaKeyPair = kpg.generateKeyPair();

// Ed25519（更轻更快）
KeyPairGenerator ed = KeyPairGenerator.getInstance("Ed25519");
KeyPair edKeyPair = ed.generateKeyPair();

3) 颁发 JWT（RS256 或 EdDSA）

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import java.time.Instant;
import java.util.Date;
import java.util.Map;

// 使用 RSA 私钥签名（RS256）
String token = Jwts.builder()
    .setHeaderParam("kid", "key-2025-08")     // 便于轮换
    .setIssuer("https://auth.example.com")
    .setSubject("user-123")
    .setAudience("api.example.com")
    .setIssuedAt(new Date())
    .setExpiration(Date.from(Instant.now().plusSeconds(900))) // 15 分钟
    .addClaims(Map.of(
        "roles", new String[]{"ADMIN","USER"},
        "tenantId", "t-1001"
    ))
    .signWith(rsaKeyPair.getPrivate())        // 默认按密钥类型选择 RS256/ES256/EdDSA
    .compact();

signWith(PrivateKey)：JJWT 会自动选合适 alg；如想强制算法，可用新版签名 API 指定 SignatureAlgorithm.

4) 验证 JWT（公钥验签 + 校验声明）

import io.jsonwebtoken.*;

Jws<Claims> jws = Jwts.parserBuilder()
    .requireIssuer("https://auth.example.com")
    .requireAudience("api.example.com")
    .setAllowedClockSkewSeconds(60) // 允许 60s 时钟偏差
    .setSigningKey(rsaKeyPair.getPublic())    // 或使用 JWKS 拉取的公钥
    .build()
    .parseClaimsJws(token);

Claims claims = jws.getBody();
String userId = claims.getSubject();
String[] roles = claims.get("roles", String[].class);

校验失败会抛异常（如 ExpiredJwtException、SignatureException）。

在网关/过滤器中统一捕获 → 返回 401/403。

六、Spring Boot（Resource Server）零胶水校验

最省心的是让 Spring Security 资源服务器替你做解析与校验，它支持 JWK 集合（JWKS） 自动远程拉取公钥。

1) 依赖

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

2) application.yml（通过 JWKS URL 校验）

server:
  port: 8080

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: https://auth.example.com/.well-known/jwks.json
          issuer-uri: https://auth.example.com   # 建议同时配置，做 iss 校验

你的授权服务器（自建或第三方，如 Auth0/Keycloak/Spring Authorization Server）对外暴露 JWKS。资源服自动缓存和轮询按 kid 取公钥。

3) 安全配置

@Bean
SecurityFilterChain security(HttpSecurity http) throws Exception {
    http
      .csrf(csrf -> csrf.disable()) // 如果前端走 Bearer 头，可关；若走 Cookie，需要保留并配置 CSRF
      .authorizeHttpRequests(reg -> reg
          .requestMatchers("/public/**").permitAll()
          .requestMatchers("/admin/**").hasRole("ADMIN")
          .anyRequest().authenticated()
      )
      .oauth2ResourceServer(oauth2 -> oauth2
          .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthConverter()))
      );
    return http.build();
}

// 可选：把自定义 claims 映射为权限
Converter<Jwt, ? extends AbstractAuthenticationToken> jwtAuthConverter() {
    return jwt -> {
        Collection<GrantedAuthority> authorities = new ArrayList<>();
        List<String> roles = jwt.getClaimAsStringList("roles");
        if (roles != null) {
            roles.forEach(r -> authorities.add(new SimpleGrantedAuthority("ROLE_" + r)));
        }
        return new JwtAuthenticationToken(jwt, authorities, jwt.getSubject());
    };
}

4) 控制器示例

@RestController
public class DemoController {

  @GetMapping("/me")
  public Map<String, Object> me(@AuthenticationPrincipal Jwt jwt) {
    return Map.of(
      "sub", jwt.getSubject(),
      "roles", jwt.getClaimAsStringList("roles"),
      "tenantId", jwt.getClaim("tenantId")
    );
  }

  @GetMapping("/admin/hello")
  public String admin() { return "hello, admin"; }
}

七、发行端：用 Spring Authorization Server 签发 JWT（概念位）

如果你既要颁发又要验证：

好处：密钥管理、轮换、标准化授权流程（OAuth2/OIDC） 都交给框架；你专注业务。

八、Cookie vs Header、CSRF 与前端存储

推荐：Authorization: Bearer <jwt> 置于请求头，前端保存在内存（刷新丢失）或安全容器；刷新策略依赖 HttpOnly Refresh Cookie。

若必须把 Access Token 放 Cookie：

不要放 localStorage（XSS 风险大）。

九、刷新与撤销（实战策略）

短期 Access Token（5–15 分钟） + 长期 Refresh Token（7–30 天）。

Refresh Token 轮换：每次刷新都颁发新 refresh，并使旧的失效（存库并维护 revoked 标记或版本号）。

黑名单/撤销：

十、微服务与网关

十一、完整示例：无授权服务器时的“轻量颁发 + 校验”

1) 颁发端（登录成功后）

// 假设你用 Spring Security 自己做用户名/密码认证
@PostMapping("/auth/login")
public Map<String, String> login(@RequestBody LoginReq req) {
    // 1. 校验用户名密码（略）
    // 2. 颁发 Token
    Instant now = Instant.now();
    String access = Jwts.builder()
        .setHeaderParam("kid", "key-2025-08")
        .setIssuer("https://auth.example.com")
        .setSubject("user-" + req.username())
        .setAudience("api.example.com")
        .setIssuedAt(Date.from(now))
        .setExpiration(Date.from(now.plusSeconds(900)))
        .claim("roles", List.of("USER"))
        .signWith(rsaPrivateKey) // 你的私钥
        .compact();

    String refreshId = UUID.randomUUID().toString(); // 存入数据库，标记有效
    String refresh = Jwts.builder()
        .setIssuer("https://auth.example.com")
        .setSubject("user-" + req.username())
        .setId(refreshId)
        .setIssuedAt(Date.from(now))
        .setExpiration(Date.from(now.plusSeconds(30 * 24 * 3600))) // 30 天
        .signWith(rsaPrivateKey)
        .compact();

    // refresh 建议放 HttpOnly Cookie 返回
    return Map.of("access_token", access, "token_type", "Bearer");
}

2) 刷新端点

@PostMapping("/auth/refresh")
public Map<String, String> refresh(@CookieValue("refresh_token") String refreshToken) {
    // 1. 验证 refreshToken 签名与过期
    Jws<Claims> jws = Jwts.parserBuilder()
        .setSigningKey(rsaPublicKey)
        .build()
        .parseClaimsJws(refreshToken);

    String jti = jws.getBody().getId();
    // 2. 校验 jti 是否未吊销，且未被使用（轮换）
    // 3. 颁发新 access（并轮换 refresh：生成新 refresh，旧的置为 revoked）

    String newAccess = ...;
    // Set-Cookie: refresh_token=<new>; HttpOnly; Secure; SameSite=Strict
    return Map.of("access_token", newAccess, "token_type", "Bearer");
}

3) 资源服务（校验端，若不用 Resource Server Starter）

自定义过滤器（不建议重复造轮子，演示用）：

@Component
public class JwtAuthFilter extends OncePerRequestFilter {

  private final PublicKey publicKey;

  public JwtAuthFilter(PublicKey publicKey) { this.publicKey = publicKey; }

  @Override
  protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
      throws ServletException, IOException {

    String auth = req.getHeader("Authorization");
    if (auth != null && auth.startsWith("Bearer ")) {
      String token = auth.substring(7);
      try {
        Jws<Claims> jws = Jwts.parserBuilder()
            .requireIssuer("https://auth.example.com")
            .requireAudience("api.example.com")
            .setAllowedClockSkewSeconds(60)
            .setSigningKey(publicKey)
            .build()
            .parseClaimsJws(token);

        Claims c = jws.getBody();
        List<GrantedAuthority> auths = new ArrayList<>();
        List<String> roles = c.get("roles", List.class);
        if (roles != null) roles.forEach(r -> auths.add(new SimpleGrantedAuthority("ROLE_" + r)));

        UsernamePasswordAuthenticationToken authentication =
            new UsernamePasswordAuthenticationToken(c.getSubject(), null, auths);

        SecurityContextHolder.getContext().setAuthentication(authentication);
      } catch (JwtException e) {
        res.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        return;
      }
    }
    chain.doFilter(req, res);
  }
}

十二、测试要点清单（上线前自查）

总结

以上为个人经验，希望能给大家一个参考，也希望大家多多支持脚本之家。

您可能感兴趣的文章:
阅读全文