Skip to content
TungDaDev's Blog

Spring Security với JWT: OAuth2 Resource Server và khóa RSA

Black iphone 5 beside brown framed eyeglasses and black iphone 5 c
Published on
11 mins read

Bạn cần thêm đăng nhập bằng JWT cho một REST API Spring Boot. Search một lúc, gần như bài nào cũng bảo kéo thư viện ngoài (jjwt, java-jwt) về, tự viết OncePerRequestFilter bóc header Authorization, rồi tự bắt exception đủ kiểu.

Chạy thì vẫn chạy. Có điều đó là cả một mớ code bảo mật bạn phải tự giữ.

Spring Security thật ra đã có sẵn module OAuth2 Resource Server lo trọn luồng này, với NimbusJwtDecoder và NimbusJwtEncoder chính chủ (decode JWT có từ bản 5.1, NimbusJwtEncoder để tự phát token có từ bản 5.6). Phần dưới dựng một API dùng nó, ký token bằng cặp khóa RSA (RS256).

# cấu hình

Vào Spring Initializr, tạo một dự án dùng Java 21, Maven, Jar và các dependency sau:

  • Spring Data JPA
  • Spring Web
  • Lombok
  • Spring Security
  • PostgreSQL Driver
  • OAuth2 Resource Server

# thiết lập cơ sở dữ liệu postgreSQL

Mình dùng Docker Compose để chạy PostgreSQL. Tạo file docker-compose.yaml ở thư mục gốc của dự án.

services:
  postgre:
    image: postgres:18
    ports:
      - '5432:5432'
    environment:
      - POSTGRES_DB=database
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=admin
    volumes:
      - postgres_data:/var/lib/postgresql
 
volumes:
  postgres_data:

Chạy docker compose up -d để khởi động container.

Để ý chỗ mount volume: từ PostgreSQL 18, image chính thức lưu data ở /var/lib/postgresql/18/docker và khuyên mount cả thư mục /var/lib/postgresql. Nếu vẫn mount kiểu cũ vào /var/lib/postgresql/data thì container 18 sẽ báo lỗi rồi thoát ngay. Cũng vì vậy mà nên ghi rõ major version (postgres:18) thay vì latest: hôm nào latest nhảy lên bản mới, data cũ sẽ không tự nâng cấp theo.

Thêm file application.properties để cấu hình cho ứng dụng Spring Boot:

# Database Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/database
spring.datasource.username=admin
spring.datasource.password=admin
spring.datasource.driver-class-name=org.postgresql.Driver
 
# JPA Configuration
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.show-sql=true
 
# Server Configuration
server.port=8080

Trong đó:

  • spring.datasource.url: URL kết nối tới PostgreSQL.
  • spring.datasource.username: tên người dùng PostgreSQL.
  • spring.datasource.password: mật khẩu truy cập database.
  • spring.jpa.hibernate.ddl-auto: tự động cập nhật schema database. update tiện khi học và chạy local, còn production thì nên quản lý schema bằng Flyway hoặc Liquibase.
  • spring.jpa.properties.hibernate.dialect: từ Hibernate 6, dialect được tự nhận diện từ kết nối nên dòng này có thể bỏ (để lại thì Hibernate chỉ log một cảnh báo).
  • spring.jpa.show-sql: in câu SQL ra console để debug.
  • server.port: cổng chạy ứng dụng (mặc định là 8080).

Database, user và mật khẩu ở đây khớp với file docker-compose.yaml bên trên. Chạy thật thì đổi sang thông tin của bạn, và đừng để mật khẩu thật nằm trong file commit lên repo (dùng biến môi trường như SPRING_DATASOURCE_PASSWORD).

# tạo khóa private và public cho jwt

Mình ký JWT bằng RSA (thuật toán RS256): server giữ khóa private để ký token, còn ai có khóa public đều kiểm tra được chữ ký nhưng không tự tạo token giả được. Cách này hợp khi về sau có thêm service khác cần xác minh token: chỉ việc đưa họ khóa public. Nếu chỉ một ứng dụng vừa ký vừa kiểm thì một khóa bí mật dùng chung (HS256) cũng được, nhưng lộ khóa đó là lộ luôn quyền ký.

Các bước tạo khóa private và public cho JWT:

Tạo khóa Private:

Chạy lệnh sau trong terminal để tạo khóa private trong thư mục resources:

openssl genpkey -algorithm RSA -out src/main/resources/private.pem

Tạo khóa Public (từ khóa Private):

openssl rsa -pubout -in src/main/resources/private.pem -out src/main/resources/public.pem

Lưu ý:

  • Không bao giờ commit private.pem lên GitHub. Khóa public thì không bí mật, nhưng để chung chỗ với khóa private cho dễ quản lý cũng được.
  • Lệnh genpkey ở trên mặc định tạo khóa RSA 2048 bit, định dạng PKCS#8 (BEGIN PRIVATE KEY), đúng định dạng Spring Security đọc được.
  • Để khóa trong src/main/resources chỉ hợp cho lúc học: nó sẽ bị đóng gói vào file jar. Chạy thật thì đặt file ở ngoài và trỏ tới bằng file:/đường/dẫn/private.pem, hoặc lấy từ secret manager.

Update application.properties để thêm các key vào cấu hình:

jwt.private.key=classpath:private.pem
jwt.public.key=classpath:public.pem

# code thôi nào

Tạo class SecurityConfig.java trong thư mục configs với nội dung sau:

import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;
 
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.web.SecurityFilterChain;
 
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.ImmutableJWKSet;
 
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
 
    @Value("${jwt.public.key}")
    private RSAPublicKey publicKey;
 
    @Value("${jwt.private.key}")
    private RSAPrivateKey privateKey;
 
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .csrf(csrf -> csrf.disable())
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(auth -> auth.requestMatchers(HttpMethod.POST, "/signin").permitAll()
                        .requestMatchers(HttpMethod.POST, "/login").permitAll()
                        .anyRequest().authenticated())
                .oauth2ResourceServer(config -> config.jwt(jwt -> jwt.decoder(jwtDecoder())));
 
        return http.build();
    }
 
    @Bean
    BCryptPasswordEncoder bPasswordEncoder() {
        return new BCryptPasswordEncoder();
    }
 
    @Bean
    JwtEncoder jwtEncoder() {
        var jwk = new RSAKey.Builder(this.publicKey).privateKey(this.privateKey).build();
 
        var jwks = new ImmutableJWKSet<>(new JWKSet(jwk));
 
        return new NimbusJwtEncoder(jwks);
    }
 
    @Bean
    JwtDecoder jwtDecoder() {
        return NimbusJwtDecoder.withPublicKey(publicKey).build();
    }
}

Điểm qua những chỗ quan trọng trong SecurityConfig.

@EnableWebSecurity bật bộ filter bảo mật web, còn @EnableMethodSecurity cho phép kiểm tra quyền ngay trên từng hàm bằng @PreAuthorize, @PostAuthorize.

privateKey và publicKey là cặp khóa RSA dùng để ký và xác minh JWT. Trong application.properties ta chỉ khai báo chuỗi đường dẫn classpath:private.pem. Việc đọc file PEM và chuyển thành RSAPrivateKey/RSAPublicKey do converter đăng ký sẵn của Spring Security (RsaKeyConversionServicePostProcessor) tự lo.

SessionCreationPolicy.STATELESS và csrf.disable() tắt việc tạo HttpSession và tắt bảo vệ CSRF. Tắt được CSRF là vì kiểu tấn công này lợi dụng chuyện trình duyệt tự đính kèm cookie vào request, mà ở đây token nằm trong header Authorization do code frontend chủ động gắn vào. Nếu bạn đổi sang lưu JWT trong cookie thì bắt buộc phải bật lại CSRF.

authorizeHttpRequests mở tự do (permitAll()) cho hai API POST /signin (đăng ký) và POST /login (đăng nhập). Mọi endpoint còn lại đều bắt buộc có token hợp lệ (authenticated()).

oauth2ResourceServer bật BearerTokenAuthenticationFilter có sẵn của Spring Security. Filter này tự rút token từ header Authorization: Bearer ... rồi đưa cho bean jwtDecoder xác thực, nên bạn khỏi phải tự viết OncePerRequestFilter.

BCryptPasswordEncoder băm mật khẩu một chiều bằng BCrypt. Nó tự sinh salt ngẫu nhiên và cho chỉnh độ nặng strength để chống dò mật khẩu brute-force.

JwtEncoder và JwtDecoder dùng thư viện Nimbus bên dưới. NimbusJwtEncoder bọc cặp khóa vào một ImmutableJWKSet để ký token bằng khóa private. NimbusJwtDecoder thì chỉ cần khóa public để kiểm tra chữ ký kèm hạn sử dụng (exp, nbf, cho phép lệch đồng hồ tối đa 60 giây). Token hết hạn hoặc sai chữ ký bị trả về 401 Unauthorized ngay ở tầng filter.

Class ClientEntity lưu trữ thông tin user:

import org.springframework.security.crypto.password.PasswordEncoder;
 
import com.fasterxml.jackson.annotation.JsonIgnore;
 
import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.EnumType;
import jakarta.persistence.Enumerated;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
 
@Entity
@Table(name = "tb_clients")
@Getter
@Setter
@NoArgsConstructor
public class ClientEntity {
 
    @Id
    @GeneratedValue(strategy = GenerationType.SEQUENCE)
    @Column(name = "client_id")
    private Long clientId;
 
    private String name;
 
    @Column(unique = true)
    private String cpf;
 
    @Column(unique = true)
    private String email;
 
    @JsonIgnore
    private String password;
 
    @Column(name = "user_type")
    private String userType = "client";
 
    public Boolean isLoginCorrect(String password, PasswordEncoder passwordEncoder) {
        return passwordEncoder.matches(password, this.password);
    }
}

cpf là mã số định danh cá nhân ở Brazil (code gốc lấy từ một bài hướng dẫn của dev Brazil), bạn đổi thành số CCCD hay username tuỳ hệ thống. @JsonIgnore trên password để khi controller trả entity về, chuỗi hash mật khẩu không lọt ra response. Làm kỹ hơn thì trả về một DTO riêng thay vì trả thẳng entity.

Class ClientRepository làm việc trực tiếp với database:

import java.util.Optional;
 
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
 
import com.tungdadev.spring_jwt.entities.ClientEntity;
 
@Repository
public interface ClientRepository extends JpaRepository<ClientEntity, Long> {
    Optional<ClientEntity> findByEmail(String email);
 
    Optional<ClientEntity> findByCpf(String cpf);
 
    Optional<ClientEntity> findByEmailOrCpf(String email, String cpf);
}

Các Service để xử lý logic:

  • Client service:
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;
 
import com.tungdadev.spring_jwt.entities.ClientEntity;
import com.tungdadev.spring_jwt.repositories.ClientRepository;
 
@Service
public class ClientService {
 
    @Autowired
    private ClientRepository clientRepository;
 
    @Autowired
    private BCryptPasswordEncoder bPasswordEncoder;
 
    public ClientEntity createClient(String name, String cpf, String email, String password) {
 
        var clientExists = this.clientRepository.findByEmailOrCpf(email, cpf);
 
        if (clientExists.isPresent()) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Email/Cpf already exists.");
        }
 
        var newClient = new ClientEntity();
 
        newClient.setName(name);
        newClient.setCpf(cpf);
        newClient.setEmail(email);
        newClient.setPassword(bPasswordEncoder.encode(password));
 
        return clientRepository.save(newClient);
    }
}
  • Token service:
import java.time.Instant;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.oauth2.jwt.JwtClaimsSet;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.JwtEncoderParameters;
import org.springframework.stereotype.Service;
 
import com.tungdadev.spring_jwt.repositories.ClientRepository;
 
@Service
public class TokenService {
 
    @Autowired
    private ClientRepository clientRepository;
 
    @Autowired
    private JwtEncoder jwtEncoder;
 
    @Autowired
    private BCryptPasswordEncoder bCryptPasswordEncoder;
 
    public String login(String email, String password) {
 
        var client = this.clientRepository.findByEmail(email)
                .orElseThrow(() -> new BadCredentialsException("Email/password invalid"));
 
        var isCorrect = client.isLoginCorrect(password, bCryptPasswordEncoder);
 
        if (!isCorrect) {
            throw new BadCredentialsException("Email/password invalid");
        }
 
        var now = Instant.now();
        var expiresIn = 300L;
 
        var claims = JwtClaimsSet.builder()
                .issuer("pic_pay_backend")
                .subject(client.getEmail())
                .issuedAt(now)
                .expiresAt(now.plusSeconds(expiresIn))
                .claim("scope", client.getUserType())
                .build();
 
        var jwtValue = jwtEncoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
 
        return jwtValue;
 
    }
}

Sai email hay sai mật khẩu đều trả cùng một lỗi BadCredentialsException. Nếu báo riêng "Email not found" thì kẻ tấn công thử vài lần là biết email nào có tài khoản trong hệ thống.

Hệ thống thật còn phải chống cả timing attack. Không tìm thấy email thì hàm thoát ngay trong vài ms, còn có email thì BCrypt mất cỡ vài chục tới vài trăm ms để băm, tuỳ strength. Cách chuẩn là vẫn chạy một lần băm giả, hoặc để DaoAuthenticationProvider của Spring Security lo sẵn việc đó.

Token chỉ sống 300 giây (5 phút). Vì JWT là stateless, server không lưu gì nên cũng không "thu hồi" được một token đã phát ra: ai cầm token thì dùng được tới lúc hết hạn. Vì vậy người ta mới để access token ngắn hạn, kèm một refresh token sống lâu hơn (lưu phía server để còn thu hồi được) dùng để xin access token mới. Bài này dừng ở access token cho gọn. Claim scope mang giá trị client sẽ được JwtAuthenticationConverter mặc định đổi thành authority SCOPE_client, chỗ này dùng lại ở controller bên dưới.

Cuối cùng là Controller, nơi nhận request. Hai DTO dùng trong controller chỉ là record đơn giản (đặt trong package controllers.dto):

public record NewClientDTO(String name, String cpf, String email, String password) {}
 
public record LoginDTO(String email, String password) {}
  • Client controller:
package com.tungdadev.spring_jwt.controllers;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationToken;
import com.tungdadev.spring_jwt.controllers.dto.NewClientDTO;
import com.tungdadev.spring_jwt.entities.ClientEntity;
import com.tungdadev.spring_jwt.services.ClientService;
 
@RestController
public class ClientController {
 
    @Autowired
    private ClientService clientService;
 
    @PostMapping("/signin")
    public ResponseEntity<ClientEntity> createNewClient(@RequestBody NewClientDTO client) {
        var newClient = this.clientService.createClient(client.name(), client.cpf(), client.email(), client.password());
 
        return ResponseEntity.status(HttpStatus.CREATED).body(newClient);
    }
 
    @GetMapping("/protectedRoute")
    @PreAuthorize("hasAuthority('SCOPE_client')")
    public ResponseEntity<String> protectedRoute(JwtAuthenticationToken token) {
        return ResponseEntity.ok("Authorized");
    }
 
}

Cách hoạt động của /protectedRoute:

  • Để gọi vào route này, client phải đính kèm JWT nhận được sau khi đăng nhập vào header Authorization:
Authorization: Bearer <your-jwt-token>
  • @PreAuthorize("hasAuthority('SCOPE_client')") chặn ngay trước khi hàm protectedRoute() kịp chạy: Spring Security đối chiếu danh sách quyền trong JwtAuthenticationToken (được dịch từ claim scope trong token sang tiền tố SCOPE_) xem có SCOPE_client hay không; thiếu quyền sẽ trả về 403 Forbidden. Nếu cần lấy thông tin người đang gọi (như email ở token.getName() hay toàn bộ claims ở token.getTokenAttributes()), bạn đọc thẳng từ tham số JwtAuthenticationToken được truyền vào hàm.

  • Token Controller: nơi xử lý đăng nhập và trả JWT về cho client.

package com.tungdadev.spring_jwt.controllers;
 
import java.util.Map;
 
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.RestController;
 
import com.tungdadev.spring_jwt.controllers.dto.LoginDTO;
import com.tungdadev.spring_jwt.services.TokenService;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
 
@RestController
public class TokenController {
 
    @Autowired
    private TokenService tokenService;
 
    @PostMapping("/login")
    public ResponseEntity<Map<String, String>> login(@RequestBody LoginDTO loginDTO) {
        var token = this.tokenService.login(loginDTO.email(), loginDTO.password());
 
        return ResponseEntity.ok(Map.of("token", token));
    }
 
}

# lời kết

Thử nhanh bằng ba request: POST /signin tạo tài khoản, POST /login lấy token, rồi gọi GET /protectedRoute hai lần, một lần có header Authorization: Bearer ... và một lần không. Lần không có token phải ra 401. Đợi hơn 6 phút (5 phút token sống cộng 60 giây lệch đồng hồ được cho phép) rồi gọi lại bằng token cũ cũng phải ra 401.

Trước khi đưa code này ra khỏi máy local, soát lại ba chỗ: private.pem không nằm trong repo hay trong file jar, mật khẩu database lấy từ biến môi trường, và ddl-auto=update đã nhường chỗ cho Flyway hoặc Liquibase. Việc đáng làm tiếp theo là thêm refresh token, vì access token 5 phút thì người dùng sẽ bị đá ra khá thường xuyên.

Nếu còn lăn tăn nên dùng session hay JWT ngay từ đầu, xem lại bài session, cookies & jwt.

Chỉ là những ghi chép cá nhân với hy vọng mang lại chút giá trị. Nếu thấy hữu ích, đừng ngại chia sẻ cho bạn bè & đồng nghiệp nhé!

Happy coding 😎 👍🏻 🚀 🔥.

Reference: