Spring Security中基于数据库的Opaque Token实现方案咨询

核心逻辑梳理 #

客户端请求时携带Bearer <token>请求头，服务端需要完成以下步骤：

1. 从请求头提取Token
2. 校验Token在数据库中是否存在、未过期、状态有效
3. 获取关联的用户信息与权限列表
4. 验证用户是否具备访问当前API的权限

以下是具体实现步骤，以及你找到的两个方法的核心指引：

一、定义数据库模型 #

首先需要在数据库中存储Token、用户及权限相关数据：

• Token表：存储token_hash（建议存哈希值，避免原始Token泄露风险）、user_id（关联用户）、expire_time（过期时间）、status（有效/无效标记）
• 用户权限表：用户表、角色表、用户-角色关联表（或直接存储用户权限列表），用于关联Token对应的权限信息

二、实现自定义Token校验器（核心入口） #

你找到的两篇资料核心都指向了OpaqueTokenIntrospector这个接口——这是Spring Security处理Opaque Token校验的核心扩展点，默认逻辑是调用认证服务器的introspect接口，你需要替换为自己的数据库校验逻辑：

1. 自定义实现类：

@Component
public class DbOpaqueTokenIntrospector implements OpaqueTokenIntrospector {

    @Autowired
    private TokenRepository tokenRepository;
    @Autowired
    private UserRepository userRepository;

    @Override
    public OAuth2AuthenticatedPrincipal introspect(String token) {
        // 1. 对传入的Token做哈希处理（和存储时的哈希规则一致）
        String tokenHash = DigestUtils.sha256Hex(token);
        
        // 2. 查询数据库中的Token记录
        TokenEntity tokenEntity = tokenRepository.findByTokenHashAndStatus(tokenHash, TokenStatus.VALID)
                .orElseThrow(() -> new OAuth2AuthenticationException(new OAuth2Error("invalid_token", "Token不存在或无效", null)));
        
        // 3. 检查Token是否过期
        if (tokenEntity.getExpireTime().isBefore(LocalDateTime.now())) {
            throw new OAuth2AuthenticationException(new OAuth2Error("invalid_token", "Token已过期", null));
        }
        
        // 4. 获取关联用户与权限信息
        UserEntity user = userRepository.findById(tokenEntity.getUserId())
                .orElseThrow(() -> new OAuth2AuthenticationException(new OAuth2Error("invalid_token", "关联用户不存在", null)));
        Set<String> authorities = user.getRoles().stream()
                .map(RoleEntity::getAuthority)
                .collect(Collectors.toSet());
        
        // 5. 返回认证信息，供Spring Security后续权限校验使用
        return new DefaultOAuth2AuthenticatedPrincipal(
                user.getUsername(),
                Map.of("userId", user.getId()),
                AuthorityUtils.createAuthorityList(authorities.toArray(new String[0]))
        );
    }
}

三、配置Spring Security资源服务器 #

在Security配置类中，指定使用自定义的Token校验器，并配置API权限规则：

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Autowired
    private DbOpaqueTokenIntrospector dbOpaqueTokenIntrospector;

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/api/public/**").permitAll()
                        .requestMatchers("/api/user/**").hasAuthority("ROLE_USER")
                        .requestMatchers("/api/admin/**").hasAuthority("ROLE_ADMIN")
                        .anyRequest().authenticated()
                )
                .oauth2ResourceServer(oauth2 -> oauth2
                        .opaqueToken(token -> token.introspector(dbOpaqueTokenIntrospector))
                );
        return http.build();
    }
}

四、权限校验的两种方式 #

1. 全局配置：通过上面SecurityFilterChain中的requestMatchers配置不同路径的权限要求
2. 方法级校验：在控制器方法上使用@PreAuthorize注解，比如：

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

    @GetMapping("/profile")
    @PreAuthorize("hasAuthority('ROLE_USER')")
    public ResponseEntity<UserProfile> getUserProfile() {
        // 业务逻辑
    }
}

关于你找到的两篇资料说明 #

• 方法1（Hashnode文章）：主要讲解了OAuth2 Opaque Token的基础概念，以及Spring Security资源服务器的基础配置，核心是告诉你可以替换默认的Token校验逻辑——这正是你需要的数据库校验入口
• 方法2（Spring官方文档）：官方标准教程，明确指出通过自定义OpaqueTokenIntrospector来扩展Opaque Token的校验逻辑，是实现数据库存储Token校验的官方标准方案

新手注意点 #

• Token哈希存储：永远不要在数据库中存储原始Token，使用SHA-256等哈希算法存储，防止数据库泄露导致Token被盗用
• 过期与失效处理：定期清理过期Token，用户注销/修改密码时要标记对应Token为无效
• 异常处理：可以自定义AuthenticationEntryPoint来统一处理Token无效/过期时的返回信息，提升客户端体验

内容的提问来源于stack exchange，提问作者Youtech code