在前面的文章中，我們深入探討了 Spring Security 的相關設定

今天，我們將進一步提升我們的 API 安全性，介紹如何使用 JWT (JSON Web Token) 實現無狀態的身分驗證

什麼是 JWT?

JWT 是一種開放標準 (RFC 7519)，它定義了一種簡潔的、自定義的方法，用於在雙方之間安全地傳輸資訊作為 JSON 對象

這些信息可以被驗證和信任，因為它是經過簽名的

JWT 由三部分組成，以點 (.) 分隔

• Header (標頭)
• Payload (負載)
• Signature (簽名)

為什麼 API 使用 JWT 是更好的認證方法 ?

• 無狀態和可擴展性: 伺服器不需要儲存 session 信息，這使得應用更容易擴展
• 跨網域認證: JWT 可以在多個服務之間共享，非常適合微服務架構
• 性能: 不需要在伺服器端查詢資料庫來驗證使用者身份
• 靈活性: 可以攜帶額外的使用者資訊，減少資料庫查詢

修改 Spring Security 配置,加入 JWT 功能

增加 JWT 依賴

// https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt-api
implementation 'io.jsonwebtoken:jjwt-api:0.12.6'

// https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt-impl
runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.6'

// https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt-jackson
runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.6'

設定 JWT 的密鑰和過期時間

先在 application.properties 裡面加入兩個值 secret 和 expiration

# JWT 用於簽名和驗證
jwt.secret=0191eb1feacf719c898518c598134bba4ac6dead4464943885810c7d3938c26
# JWT token 的過期時間，以秒為單位（這裡設置為 24 小時）
jwt.expiration=86400

建立一個 JwtService 來處理 JWT 的生成和驗證

@Service
public class JwtService {

    // 使用 @Value 簡單的注入 properties 裡面的 JWT 密鑰和過期時間
    @Value("${jwt.secret}")
    private String secret;

    @Value("${jwt.expiration}")
    private Long expiration;

    public String generateToken(UserDetails userDetails) {
        // 可以加入想要放在 token 裡面的 claims
        Map<String, Object> claims = new HashMap<>();

        return createToken(claims, userDetails.getUsername());
    }

    // 產生 JWT Token，用使用者的 username 來當成 subject
    private String createToken(Map<String, Object> claims, String subject) {
        return Jwts.builder()
                .claims(claims)
                .subject(subject)
                .issuedAt(new Date(System.currentTimeMillis()))
                .expiration(new Date(System.currentTimeMillis() + expiration * 1000))
                .signWith(getSigningKey())
                .compact();
    }

    // 驗證使用者傳來的 JWT 是不是合法的
    public Boolean validateToken(String token, UserDetails userDetails) {
        final String username = extractUsername(token);
        return (username.equals(userDetails.getUsername()) && !isTokenExpired(token));
    }

    // 從 JWT 取出裡面的 Subject (使用者的 username)
    public String extractUsername(String token) {
        return extractClaim(token, Claims::getSubject);
    }

    // 把 properties 裡面的 JWT 密鑰，轉換成 Java 的 SecretKey (簽名密鑰)
    private SecretKey getSigningKey() {
        byte[] keyBytes = secret.getBytes();
        return Keys.hmacShaKeyFor(keyBytes);
    }

    // 從 JWT 取出裡面的 Expiration (過期時間)
    private Date extractExpiration(String token) {
        return extractClaim(token, Claims::getExpiration);
    }

    // 取出 JWT 特定的 Claim
    private <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = extractAllClaims(token);
        return claimsResolver.apply(claims);
    }

    // 取出 JWT 的所有 Claims
    private Claims extractAllClaims(String token) {
        return Jwts.parser()
                .verifyWith(getSigningKey())
                .build()
                .parseSignedClaims(token)
                .getPayload();
    }

    // JWT 有沒有過期
    private Boolean isTokenExpired(String token) {
        return extractExpiration(token).before(new Date());
    }
}

建立 JWT 請求過濾器

建立一個 JwtRequestFilter 攔截每個請求並驗證 JWT

// 繼承 OncePerRequestFilter，確保每個請求只執行一次過濾
@Component
public class JwtRequestFilter extends OncePerRequestFilter {

    // 這裡只列出 JWT 相關的程式碼，而不是全部的程式碼

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

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

        String username = null;
        String jwt = null;

        // 從 Header 裡面取出 JWT，並且拿出 JWT 裡面的 username
        if (authorizationHeader != null && authorizationHeader.startsWith("Bearer ")) {
            jwt = authorizationHeader.substring(7);
            username = jwtService.extractUsername(jwt);
        }

        // 如果有 JWT (有 username)，而且是未登入狀態
        if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {

            // 使用 JWT 的 username 去找到使用者相關的資料，這裡是從資料庫裡面取出資料
            UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);

            // 驗證 JWT 是不是有效的
            if (jwtService.validateToken(jwt, userDetails)) {

                // 如果 JWT 是有效的，就設定到 Spring Security 的 Context，表示使用者已經登入
                var usernamePasswordAuthenticationToken = new UsernamePasswordAuthenticationToken(
                        userDetails,
                        null,
                        userDetails.getAuthorities());

                usernamePasswordAuthenticationToken
                        .setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(usernamePasswordAuthenticationToken);
            }
        }

        filterChain.doFilter(request, response);
    }
}

修改 Spring Security 配置

更新 SecurityConfig 以支持 JWT

public class SecurityConfig {

    // 這裡只列出 JWT 相關的程式碼，而不是全部的程式碼

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {

        http.authorizeHttpRequests((requests) -> requests
                        // 允許所有人訪問 api/auth 下面的 API
                        .requestMatchers("/api/auth/**").permitAll()
                        // 要求所有其他請求都必須經過認證
                        .anyRequest().authenticated()
                )
                // 設定 session 管理策略為無狀態（STATELESS）
                // 表示應用程式不會為每個使用者儲存相關的 session，這是基於令牌的認證方案 (JWT) 的典型設定
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                // 設定 JWT 請求過濾器，來驗證 JWT，並將其放置在 UsernamePasswordAuthenticationFilter 之前
                // 確保了 JWT 的驗證在使用者名密碼驗證之前進行
                .addFilterBefore(jwtRequestFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    // 建立一個 AuthenticationManager bean
    // AuthenticationManager 是 Spring Security 用於處理認證請求的核心功能
    @Bean
    public AuthenticationManager authenticationManager(AuthenticationConfiguration authenticationConfiguration) throws Exception {
        // 使用 AuthenticationConfiguration 來取得預設的 AuthenticationManager
        return authenticationConfiguration.getAuthenticationManager();
    }
}

新增獲取 JWT 的 API

建立一個新的 controller 來處理，登入後回傳 JWT 的 API

@RestController
@RequestMapping("/api/auth")
public class AuthController {

    // 這裡只列出 JWT 相關的程式碼，而不是全部的程式碼

    @PostMapping("/login")
    public ResponseEntity<MyApiResponse<AuthenticationResponse>> createAuthenticationToken(@RequestBody AuthenticationRequest authenticationRequest) throws Exception {

        try {
            // 使用帳號和密碼驗證是否可以登入
            authenticationManager.authenticate(
                    new UsernamePasswordAuthenticationToken(authenticationRequest.username(),
                            authenticationRequest.password())
            );
        } catch (BadCredentialsException e) {
            throw new Exception("Incorrect username or password", e);
        }

        // 帳號和密碼認證過了
        // 從資料庫取得使用者相關資料
        final UserDetails userDetails = userDetailsService
                .loadUserByUsername(authenticationRequest.username());

        // 使用相關資料產生 JWT
        final String jwt = jwtService.generateToken(userDetails);

        var authenticationResponse = new AuthenticationResponse(jwt);

        return ResponseEntity.ok(new MyApiResponse<>(true, authenticationResponse, null));
    }
}

測試 API

全部完成後，就可以呼叫 API 來測試

可以看到登入後，就有取得 JWT

把 JWT 拿到 jwt.io ，來看一下裡面的相關 payload 

可以看到 subject 為 user，還有相關的時間

把原本 API 的基本 HTTP 認證（Basic Authentication）改為使用 JWT 認證 

同場加映：修改測試程式碼支援 JWT

TodoEndToEnd Test

寫一個 getJwtToken 的方法，來實際取得 JWT

然後在 BeforeEach 的時候，把它設定為 全局變數，每一個測試就可以用到了

public class TodoEndToEndTest {

    // 這裡只列出 JWT 相關的程式碼，而不是全部的程式碼

    @BeforeEach
    void setUp() {

        // 獲取 JWT Token 並設置為全局變數
        String token = getJwtToken();
        RestAssured.requestSpecification = given()
                .header(new Header("Authorization", "Bearer " + token));
    }
    
    // 新增一個方法來獲取 JWT Token
    private String getJwtToken() {

        return given()
                .contentType(ContentType.JSON)
                .body(new AuthenticationRequest(username, password))
                .when()
                .post("/api/auth/login")
                .then()
                .statusCode(200)
                .extract()
                .path("data.jwt");
    }
}

TodoController Test

因為我們加入了 JwtRequestFilter ，在使用 MockMvc 來執行測試的話，會說找不到 JwtRequestFilter 

必須要把它相關使用到的類別給顯示 Import 進來

另外，因為 UserRepository 它是 interface，需要用 MockBean 的方式

// 這裡只列出 JWT 相關的程式碼，而不是全部的程式碼

@WebMvcTest(TodoController.class)
@Import({JwtRequestFilter.class, CustomUserDetailsService.class, JwtService.class})
public class TodoControllerTest {

    @MockBean
    private UserRepository userRepository;
}

這樣子修改完，測試就又可以動了 XD

結論

通過實現 JWT，我們成功地為我們的 API 添加了一個無狀態的身份驗證系統

這種方法不僅提高了應用的安全性，還增強了其可擴展性

然而，在實際應用中，我們還需要考慮一些額外的安全措施

例如

• 定期更換密鑰
• 實現 JWT 刷新機制
• 處理 JWT 撤銷

同步刊登於 Blog 「Spring Boot API 開發：從 0 到 1」Day 35 JWT 實現無狀態身份驗證

我的粉絲專頁

圖片來源：AI 產生

參考連結

• https://datatracker.ietf.org/doc/html/rfc7519
• https://jwt.io
• https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html
• https://github.com/jwtk/jjwt