本文档旨在指导开发者如何使用 Spring Security 限制 JWT 刷新令牌的使用范围，确保刷新令牌只能用于特定的刷新端点。通过修改令牌生成逻辑和 Spring Security 配置，可以有效防止刷新令牌被滥用，提高系统的安全性。
理解 JWT 刷新令牌的安全风险
在使用 JWT (JSON Web Token) 进行身份验证时，通常会同时颁发访问令牌（Access Token）和刷新令牌（Refresh Token）。访问令牌的有效期较短，用于访问受保护的资源。当访问令牌过期后，客户端可以使用刷新令牌向授权服务器请求新的访问令牌，而无需重新进行身份验证。
然而，如果刷新令牌被泄露，攻击者就可以利用该令牌获取新的访问令牌，从而冒充合法用户访问系统资源。因此，限制刷新令牌的使用范围，使其只能用于特定的刷新端点，是提高系统安全性的重要措施。
实现方案：为访问令牌添加特定权限
一种有效的解决方案是为所有的访问令牌添加一个特定的权限，例如 "access"，并要求所有需要访问令牌的端点都必须具备该权限。这样，刷新令牌由于不包含该权限，就无法访问这些端点，从而实现了对刷新令牌使用范围的限制。
1. 修改 TokenService 类
在 JwtTokenServiceImpl 类中，修改 generateAccessToken 方法，为访问令牌添加 "access" 权限。同时，确保使用正确的 claim name，与 Spring Security 配置保持一致。
@Service
@RequiredArgsConstructor
public class JwtTokenServiceImpl implements JwtTokenService {
private final JwtEncoder jwtEncoder;
@Override
public String generateAccessToken(User user) {
Instant now = Instant.now();
String scope = user.getAuthorities().stream()
.map(GrantedAuthority::getAuthority)
.collect(Collectors.joining(" "));
// 添加 "access" 权限
String accessScope = scope.concat(" access");
JwtClaimsSet claims = JwtClaimsSet.builder()
.issuer("self")
.issuedAt(now)
.expiresAt(now.plus(2, ChronoUnit.MINUTES))
.subject(user.getUsername())
// 确保使用 "roles" 作为 claim name，与 WebSecurityConfig 保持一致
.claim("roles", accessScope)
.build();
return this.jwtEncoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
}
@Override
public String generateRefreshToken(User user) {
Instant now = Instant.now();
String scope = "ROLE_REFRESH_TOKEN";
JwtClaimsSet claims = JwtClaimsSet.builder()
.issuer("self")
.issuedAt(now)
.expiresAt(now.plus(10, ChronoUnit.MINUTES))
.subject(user.getUsername())
.claim("roles", scope)
.build();
return this.jwtEncoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
}
@Override
public String parseToken(String token) {
try {
SignedJWT decodedJWT = SignedJWT.parse(token);
return decodedJWT.getJWTClaimsSet().getSubject();
} catch (ParseException e) {
e.printStackTrace();
}
return null;
}
}注意事项：
- 请确保 accessScope 中添加的 "access" 权限与你在 WebSecurityConfig 中配置的权限名称一致。
- 在生成 JWT 时，使用 roles 作为 claim name，这与 WebSecurityConfig 中的配置相对应，避免权限解析错误。
2. 修改 WebSecurityConfig 类
在 WebSecurityConfig 类中，修改 HttpSecurity 的配置，要求所有需要访问令牌的端点都必须具备 "ROLE_access" 权限。
@Configuration
@RequiredArgsConstructor
@EnableWebSecurity
public class WebSecurityConfig {
@Value("${app.chat.jwt.public.key}")
private RSAPublicKey publicKey;
@Value("${app.chat.jwt.private.key}")
private RSAPrivateKey privateKey;
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.cors().and().csrf().disable();
http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);
http.exceptionHandling(
exceptions ->
exceptions
.authenticationEntryPoint(new BearerTokenAuthenticationEntryPoint())
.accessDeniedHandler(new BearerTokenAccessDeniedHandler()));
http.authorizeHttpRequests()
.requestMatchers("/auth/sign-in").permitAll()
.requestMatchers("/auth/sign-up").permitAll()
// 要求所有需要访问令牌的端点都必须具备 "ROLE_access" 权限
.anyRequest().hasAuthority("ROLE_access")
.and()
.httpBasic(Customizer.withDefaults())
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
return http.build();
}
@SneakyThrows
@Bean
public JwtEncoder jwtEncoder() {
var jwk = new RSAKey.Builder(publicKey).privateKey(privateKey).build();
var jwks = new ImmutableJWKSet<>(new JWKSet(jwk));
return new NimbusJwtEncoder(jwks);
}
@SneakyThrows
@Bean
public JwtDecoder jwtDecoder() {
return NimbusJwtDecoder.withPublicKey(publicKey).build();
}
@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
var jwtGrantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
// 确保使用 "roles" 作为 claim name，与 JwtTokenServiceImpl 保持一致
jwtGrantedAuthoritiesConverter.setAuthoritiesClaimName("roles");
jwtGrantedAuthoritiesConverter.setAuthorityPrefix("ROLE_");
var jwtAuthenticationConverter = new JwtAuthenticationConverter();
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(jwtGrantedAuthoritiesConverter);
return jwtAuthenticationConverter;
}
@Bean
public CorsFilter corsFilter() {
UrlBasedCorsConfigurationSource source =
new UrlBasedCorsConfigurationSource();
CorsConfiguration config = new CorsConfiguration();
config.setAllowCredentials(true);
config.addAllowedOrigin("*");
config.addAllowedHeader("*");
config.addAllowedMethod("*");
source.registerCorsConfiguration("/**", config);
return new CorsFilter(source);
}
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
@Bean
public AuthenticationManager authenticationManager(
AuthenticationConfiguration authenticationConfiguration) throws Exception {
return authenticationConfiguration.getAuthenticationManager();
}
}注意事项：
- 确保 jwtGrantedAuthoritiesConverter.setAuthoritiesClaimName("roles") 使用的 claim name 与你在 JwtTokenServiceImpl 中配置的 claim name 一致。
- 权限前缀 jwtGrantedAuthoritiesConverter.setAuthorityPrefix("ROLE_") 确保 Spring Security 正确解析权限。
3. 测试验证
完成以上配置后，重新启动应用程序并进行测试。确保以下场景能够正常工作：
- 使用有效的访问令牌可以访问受保护的资源。
- 使用刷新令牌访问受保护的资源时，应该被拒绝。
- 可以使用刷新令牌请求新的访问令牌。
进一步增强安全性：一次性刷新令牌
为了进一步增强安全性，可以考虑实现一次性刷新令牌的机制。这意味着每个刷新令牌只能使用一次，使用后立即失效。这可以有效防止刷新令牌被重复利用，即使攻击者获取了刷新令牌，也只能使用一次。
实现一次性刷新令牌通常需要在服务器端存储刷新令牌的状态，例如存储在数据库或缓存中。当收到刷新令牌的请求时，首先检查该令牌是否已经使用过，如果已经使用过，则拒绝请求。如果令牌有效，则颁发新的访问令牌和刷新令牌，并将旧的刷新令牌标记为已使用。
由于实现一次性刷新令牌涉及到状态管理，需要根据具体的业务需求和技术栈进行选择和实现。
总结
通过为访问令牌添加特定的权限，并要求所有需要访问令牌的端点都必须具备该权限，可以有效限制 JWT 刷新令牌的使用范围，提高系统的安全性。同时，可以考虑实现一次性刷新令牌的机制，进一步增强安全性。在实际应用中，需要根据具体的业务需求和安全要求，选择合适的方案。
