本教程旨在解决jwt刷新令牌权限过宽的问题，确保刷新令牌仅能用于获取新的访问令牌，而不能访问其他受保护资源。我们将通过为访问令牌添加特定权限（如“access”），并在spring security配置中强制要求所有受保护端点（刷新端点除外）具备此权限，从而实现刷新令牌的权限隔离。同时，还将纠正jwt声明名称的潜在不一致问题。
引言：刷新令牌的权限隔离需求
在基于JWT的认证系统中，通常会发放两种令牌：短生命周期的访问令牌（Access Token）和长生命周期的刷新令牌（Refresh Token）。访问令牌用于访问受保护资源，而刷新令牌的唯一目的应是获取新的访问令牌。然而，如果刷新令牌也能像访问令牌一样访问所有受保护的端点，那么短生命周期的访问令牌就失去了其核心的安全优势。一旦刷新令牌泄露，攻击者将能无限期地访问所有资源，这与系统的安全设计初衷相悖。
本教程将指导您如何在Spring Security和OAuth2 Resource Server环境下，通过精细的权限控制，确保刷新令牌仅能用于刷新操作，而不能用于访问其他业务端点。
核心思路：基于权限的令牌区分
要实现刷新令牌的权限隔离，关键在于区分不同类型的令牌所携带的权限。我们将采取以下策略：
- 访问令牌（Access Token）：包含用户的所有业务角色权限，并额外添加一个特殊的“access”权限标识。
- 刷新令牌（Refresh Token）：仅包含一个用于刷新操作的特定权限（例如ROLE_REFRESH_TOKEN），不包含“access”权限或其他业务权限。
- Spring Security配置：所有受保护的业务端点都必须要求具备“access”权限，而刷新令牌端点则要求具备ROLE_REFRESH_TOKEN权限。
这样，当刷新令牌被提交到非刷新端点时，由于它不包含“access”权限，请求将被拒绝。
实施步骤
1. 修改访问令牌生成逻辑
在JwtTokenServiceImpl中，修改generateAccessToken方法，为生成的访问令牌添加一个名为“access”的权限。这个权限将作为所有普通受保护端点访问的必要条件。
@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(" ROLE_access"); // 注意：Spring Security通常以"ROLE_"作为权限前缀
JwtClaimsSet claims = JwtClaimsSet.builder()
.issuer("self")
.issuedAt(now)
.expiresAt(now.plus(2, ChronoUnit.MINUTES))
.subject(user.getUsername())
// 使用统一的声明名称，例如"roles"
.claim("roles", accessScope) // 将权限信息存储在"roles"声明中
.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())
// 同样使用统一的声明名称"roles"
.claim("roles", scope) // 将权限信息存储在"roles"声明中
.build();
return this.jwtEncoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
}
// ... 其他方法保持不变
}注意： 在这里我们将claim("scope", scope)改为了claim("roles", accessScope)，以与JwtAuthenticationConverter中的setAuthoritiesClaimName("roles")保持一致。这是确保Spring Security正确解析JWT权限的关键。
2. 配置Spring Security以强制要求“access”权限
在WebSecurityConfig中，修改SecurityFilterChain的配置，对所有受保护的端点（除了登录、注册和刷新令牌端点）强制要求ROLE_access权限。
@Configuration
@RequiredArgsConstructor
@EnableWebSecurity
public class WebSecurityConfig {
// ... 其他配置保持不变
@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_REFRESH_TOKEN权限
.requestMatchers("/auth/token/refresh").hasAuthority("ROLE_REFRESH_TOKEN")
// 所有其他请求都必须拥有ROLE_access权限
.anyRequest().hasAuthority("ROLE_access")
.and()
.httpBasic(Customizer.withDefaults())
.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
return http.build();
}
// ... 其他Bean配置保持不变
@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
var jwtGrantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
// 确保这里设置的声明名称与JWT中存储权限的声明名称一致
jwtGrantedAuthoritiesConverter.setAuthoritiesClaimName("roles");
jwtGrantedAuthoritiesConverter.setAuthorityPrefix("ROLE_");
var jwtAuthenticationConverter = new JwtAuthenticationConverter();
jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(jwtGrantedAuthoritiesConverter);
return jwtAuthenticationConverter;
}
// ... 其他Bean配置保持不变
}解释：
- requestMatchers("/auth/token/refresh").hasAuthority("ROLE_REFRESH_TOKEN")：明确指定刷新令牌端点需要ROLE_REFRESH_TOKEN权限。由于刷新令牌在生成时只包含此权限，它将能够访问此端点。
- anyRequest().hasAuthority("ROLE_access")：这是核心。所有其他未被permitAll()或特定requestMatchers规则覆盖的请求，都必须具备ROLE_access权限。由于访问令牌在生成时被赋予了ROLE_access权限，而刷新令牌没有，因此刷新令牌无法访问这些端点。
3. 移除控制器中的@PreAuthorize注解
由于我们已经在WebSecurityConfig中通过authorizeHttpRequests配置了基于URL的权限控制，AuthController中针对/auth/token/refresh端点的@PreAuthorize("hasRole('REFRESH_TOKEN')")注解可以移除，以避免潜在的混淆或重复逻辑。
@RestController
@RequestMapping("/auth")
@RequiredArgsConstructor
public class AuthController {
// ... 其他字段和方法
// @PreAuthorize("hasRole('REFRESH_TOKEN')") // 此注解现在可以移除
@GetMapping("/token/refresh")
public TokensResponse refreshToken(HttpServletRequest request) {
String headerAuth = request.getHeader("Authorization");
String previousRefreshToken = headerAuth.substring(7);
String username = tokenService.parseToken(previousRefreshToken);
var user = (User) usrDetailsService.loadUserByUsername(username);
String accessToken = tokenService.generateAccessToken(user);
String refreshToken = tokenService.generateRefreshToken(user);
return new TokensResponse(accessToken, refreshToken);
}
// ... 其他方法
}总结与注意事项
通过上述修改，我们成功地将刷新令牌的用途限制在仅获取新的访问令牌。当刷新令牌被用于访问其他受保护资源时，Spring Security将因其不具备ROLE_access权限而拒绝请求。
关键点回顾：
- 权限分离：访问令牌包含业务权限和ROLE_access，刷新令牌仅包含ROLE_REFRESH_TOKEN。
- 统一声明名称：确保JwtTokenServiceImpl中用于存储权限的JWT声明名称（例如"roles"）与JwtAuthenticationConverter中setAuthoritiesClaimName()方法设置的名称完全一致。
- Spring Security配置优先级：authorizeHttpRequests中的规则是从上到下匹配的，因此更具体的规则（如/auth/token/refresh）应放在anyRequest()之前。
进一步思考（一次性刷新令牌）：
原文中提到“一次性使用”的刷新令牌。实现这一点通常需要服务器端存储和管理刷新令牌的状态。每次刷新令牌被使用后，服务器会将其标记为已使用或将其从存储中移除，以防止重放攻击。这通常涉及数据库操作或分布式缓存，并引入额外的复杂性，例如令牌撤销机制。虽然超出了本文档的直接范围，但在生产环境中，对于更高的安全性要求，这是一个值得考虑的特性。
