Spring Security JWT 认证：深入理解与实践指南

简介

在当今的 Web 开发中，身份验证和授权是保障应用程序安全的关键环节。Spring Security 作为 Spring 框架中用于安全管理的强大工具，提供了丰富的功能来处理认证和授权。而 JSON Web Token（JWT）则是一种广泛应用于现代 Web 应用的轻量级身份验证机制，它以紧凑、自包含的方式在各方之间安全地传输信息。将 Spring Security 与 JWT 结合使用，可以构建出高效、安全且易于维护的认证体系。本文将详细介绍 Spring Security JWT 认证的基础概念、使用方法、常见实践以及最佳实践，帮助读者快速掌握并应用这一技术。

目录

1. 基础概念
   • Spring Security
   • JSON Web Token（JWT）
2. 使用方法
   • 项目搭建
   • 引入依赖
   • 配置 Spring Security
   • 生成和验证 JWT
3. 常见实践
   • 用户注册与登录
   • 保护 API 端点
   • 处理令牌过期
4. 最佳实践
   • 安全存储密钥
   • 防止令牌被盗用
   • 性能优化
5. 小结
6. 参考资料

基础概念

Spring Security

Spring Security 是一个为基于 Spring 的企业应用程序提供声明式安全访问控制解决方案的框架。它提供了全面的安全性支持，包括身份验证（用户是谁）、授权（用户被允许做什么）、防止攻击（如 CSRF、XSS 等）。Spring Security 通过过滤器链来实现安全控制，每个过滤器负责特定的安全任务。

JSON Web Token（JWT）

JWT 是一种开放标准（RFC 7519），用于在网络应用之间安全地传输声明。它通常由三部分组成：头部（Header）、载荷（Payload）和签名（Signature）。 - 头部（Header）：包含令牌的类型（通常是 JWT）和使用的签名算法，例如 HMAC SHA256 或 RSA。 - 载荷（Payload）：包含声明（claims），这些声明是关于实体（通常是用户）和其他数据的陈述。例如，用户 ID、用户名、角色等。 - 签名（Signature）：用于验证消息在传输过程中没有被更改，并且在使用私钥签名的情况下，还可以验证 JWT 的发送者的身份。

JWT 的优点包括： - 无状态：服务器不需要存储关于用户会话的任何信息，这使得应用程序更容易扩展和部署。 - 自包含：令牌本身包含了所有必要的用户信息，减少了对数据库的查询。 - 跨域友好：可以轻松地在不同的域之间传输。

使用方法

项目搭建

首先，创建一个新的 Spring Boot 项目。可以使用 Spring Initializr（https://start.spring.io/）来快速生成项目骨架。选择 Spring Web 和 Spring Security 依赖。

引入依赖

在 pom.xml 文件中添加所需的依赖：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-api</artifactId>
        <version>0.11.2</version>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-impl</artifactId>
        <version>0.11.2</version>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>io.jsonwebtoken</groupId>
        <artifactId>jjwt-jackson</artifactId>
        <version>0.11.2</version>
        <scope>runtime</scope>
    </dependency>
</dependencies>

配置 Spring Security

创建一个配置类来配置 Spring Security：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
          .csrf().disable()
          .authorizeRequests()
               .antMatchers("/authenticate").permitAll()
               .anyRequest().authenticated()
               .and()
          .httpBasic();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

在上述配置中： - csrf().disable() 禁用了跨站请求伪造保护，在某些情况下可能需要根据实际需求重新启用。 - .antMatchers("/authenticate").permitAll() 允许对 /authenticate 端点的所有请求，通常这个端点用于用户登录并获取 JWT。 - .anyRequest().authenticated() 要求所有其他请求都需要经过身份验证。 - .httpBasic() 启用了 HTTP 基本认证，这只是一个简单的示例，实际应用中可能需要更复杂的认证方式。

生成和验证 JWT

创建一个 JWT 工具类来生成和验证 JWT：

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.stereotype.Component;

import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;

@Component
public class JwtUtil {

    private static final String SECRET_KEY = "your-secret-key";
    private static final long JWT_TOKEN_VALIDITY = 5 * 60 * 60;

    public String getUsernameFromToken(String token) {
        return getClaimFromToken(token, Claims::getSubject);
    }

    public Date getExpirationDateFromToken(String token) {
        return getClaimFromToken(token, Claims::getExpiration);
    }

    public <T> T getClaimFromToken(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = getAllClaimsFromToken(token);
        return claimsResolver.apply(claims);
    }

    private Claims getAllClaimsFromToken(String token) {
        return Jwts.parserBuilder()
              .setSigningKey(SECRET_KEY)
              .build()
              .parseClaimsJws(token)
              .getBody();
    }

    private Boolean isTokenExpired(String token) {
        final Date expiration = getExpirationDateFromToken(token);
        return expiration.before(new Date());
    }

    public String generateToken(UserDetails userDetails) {
        Map<String, Object> claims = new HashMap<>();
        return doGenerateToken(claims, userDetails.getUsername());
    }

    private String doGenerateToken(Map<String, Object> claims, String subject) {
        return Jwts.builder()
              .setClaims(claims)
              .setSubject(subject)
              .setIssuedAt(new Date(System.currentTimeMillis()))
              .setExpiration(new Date(System.currentTimeMillis() + JWT_TOKEN_VALIDITY * 1000))
              .signWith(SignatureAlgorithm.HS256, SECRET_KEY)
              .compact();
    }

    public Boolean validateToken(String token, UserDetails userDetails) {
        final String username = getUsernameFromToken(token);
        return (username.equals(userDetails.getUsername()) &&!isTokenExpired(token));
    }
}

在上述代码中： - SECRET_KEY 是用于签名 JWT 的密钥，需要妥善保管。 - JWT_TOKEN_VALIDITY 定义了 JWT 的有效时间，这里设置为 5 小时。 - generateToken 方法用于生成 JWT，它接受一个 UserDetails 对象并在令牌中包含用户信息。 - validateToken 方法用于验证 JWT 的有效性，包括检查用户名和令牌是否过期。

常见实践

用户注册与登录

创建用户服务和控制器来处理用户注册和登录：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
public class UserController {

    @Autowired
    private AuthenticationManager authenticationManager;

    @Autowired
    private UserDetailsService userDetailsService;

    @Autowired
    private JwtUtil jwtUtil;

    @PostMapping("/register")
    public String register(@RequestBody User user) {
        // 保存用户到数据库
        // 这里省略实际的数据库操作
        return "User registered successfully";
    }

    @PostMapping("/authenticate")
    public String authenticate(@RequestBody User user) throws Exception {
        Authentication authentication = authenticationManager.authenticate(
                new UsernamePasswordAuthenticationToken(user.getUsername(), user.getPassword()));

        SecurityContextHolder.getContext().setAuthentication(authentication);
        final UserDetails userDetails = userDetailsService.loadUserByUsername(user.getUsername());
        final String jwt = jwtUtil.generateToken(userDetails);

        return jwt;
    }
}

在上述代码中： - /register 端点用于用户注册，实际应用中需要将用户信息保存到数据库。 - /authenticate 端点用于用户登录，它通过 AuthenticationManager 验证用户的用户名和密码，然后生成并返回 JWT。

保护 API 端点

创建一个过滤器来验证 JWT，并在请求到达受保护的 API 端点之前进行验证：

import io.jsonwebtoken.ExpiredJwtException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@Component
public class JwtRequestFilter extends OncePerRequestFilter {

    @Autowired
    private UserDetailsService userDetailsService;

    @Autowired
    private JwtUtil jwtUtil;

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

        final String requestTokenHeader = request.getHeader("Authorization");

        String username = null;
        String jwtToken = null;

        if (requestTokenHeader!= null && requestTokenHeader.startsWith("Bearer ")) {
            jwtToken = requestTokenHeader.substring(7);
            try {
                username = jwtUtil.getUsernameFromToken(jwtToken);
            } catch (IllegalArgumentException e) {
                System.out.println("Unable to get JWT Token");
            } catch (ExpiredJwtException e) {
                System.out.println("JWT Token has expired");
            }
        } else {
            logger.warn("JWT Token is not present in header");
        }

        if (username!= null && SecurityContextHolder.getContext().getAuthentication() == null) {
            UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);

            if (jwtUtil.validateToken(jwtToken, userDetails)) {
                UsernamePasswordAuthenticationToken usernamePasswordAuthenticationToken = new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities());
                usernamePasswordAuthenticationToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(usernamePasswordAuthenticationToken);
            }
        }
        chain.doFilter(request, response);
    }
}

在上述代码中： - JwtRequestFilter 继承自 OncePerRequestFilter，确保每个请求只被过滤一次。 - 它从请求头中获取 Authorization 字段，并提取 JWT。 - 验证 JWT 的有效性，并将经过身份验证的用户信息设置到 SecurityContextHolder 中。

处理令牌过期

在 JwtRequestFilter 中已经处理了令牌过期的情况，当捕获到 ExpiredJwtException 时，可以记录日志并返回合适的错误响应给客户端。例如：

catch (ExpiredJwtException e) {
    System.out.println("JWT Token has expired");
    response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
    response.getWriter().write("JWT Token has expired");
    return;
}

最佳实践

安全存储密钥

JWT 的签名密钥非常重要，必须妥善保管。不要将密钥硬编码在代码中，建议将其存储在安全的配置文件中，并通过环境变量或配置管理工具（如 HashiCorp Vault）进行加载。

防止令牌被盗用

• 使用 HTTPS：确保所有涉及 JWT 传输的请求都使用 HTTPS，防止令牌在网络传输过程中被窃取。
• 设置合理的令牌有效期：根据应用程序的需求，设置适当的令牌有效期，减少令牌被盗用后的风险。
• 使用刷新令牌：当令牌过期时，使用刷新令牌来获取新的 JWT，避免用户频繁登录。

性能优化

• 缓存用户信息：如果应用程序频繁验证 JWT，可以考虑缓存用户信息，减少数据库查询次数。
• 批量验证：在某些情况下，可以将多个 JWT 的验证合并为一个批量操作，提高性能。

小结

本文详细介绍了 Spring Security JWT 认证的基础概念、使用方法、常见实践以及最佳实践。通过将 Spring Security 的强大安全功能与 JWT 的轻量级和无状态特性相结合，可以构建出安全、高效的认证体系。在实际应用中，需要根据具体需求进行适当的调整和优化，确保应用程序的安全性和性能。

参考资料

• Spring Security 官方文档
• JSON Web Token 官方文档
• Baeldung - Spring Security with JWT