Spring Security OAuth2 不透明令牌内省请求缓存实战指南

1. 背景与挑战

在使用spring security构建oauth2资源服务器时，如果采用不透明令牌（opaque token）模式，资源服务器需要通过内省（introspection）机制向认证服务器验证接收到的令牌。这意味着每次请求到达资源服务器时，都会触发一次对认证服务器的内省调用。当认证服务器不稳定或响应缓慢时，这可能导致资源服务器性能下降，甚至因内省失败而频繁返回401未授权错误，严重影响用户体验。为了解决这一问题，引入缓存机制来存储已验证的令牌内省结果变得至关重要。

2. Spring Security OAuth2 不透明令牌内省机制

Spring Security 5.x 提供了对OAuth2资源服务器的支持，其中不透明令牌的内省通过OpaqueTokenIntrospector接口实现。默认情况下，Spring Security会使用NimbusOpaqueTokenIntrospector，它直接通过HTTP请求与认证服务器的内省端点进行通信。

标准的Spring Security配置如下：

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Value("${spring.security.oauth2.resourceserver.opaque-token.client-id}")
    private String clientId;
    @Value("${spring.security.oauth2.resourceserver.opaque-token.client-secret}")
    private String clientSecret;
    @Value("${spring.security.oauth2.resourceserver.opaque-token.introspection-uri}")
    private String introspectionUri;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests(authorizeRequests ->
                authorizeRequests
                    .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2ResourceServer ->
                oauth2ResourceServer
                    .opaqueToken(opaqueToken ->
                        opaqueToken
                            .introspectionClientCredentials(this.clientId, this.clientSecret)
                            .introspectionUri(this.introspectionUri)
                    )
            );
    }
}

要引入缓存，我们需要替换或包装默认的OpaqueTokenIntrospector实现。

3. 实现自定义缓存型OpaqueTokenIntrospector

本节将展示如何创建一个自定义的OpaqueTokenIntrospector，利用Ehcache作为缓存解决方案，以存储和管理已内省的令牌。

3.1 定义自定义内省器

首先，创建一个名为CustomOpaqueTokenIntrospector的类，它将实现OpaqueTokenIntrospector接口，并封装一个底层的NimbusOpaqueTokenIntrospector实例。

标小兔AI写标书

一款专业的标书AI代写平台，提供专业AI标书代写服务，安全、稳定、速度快，可满足各类招投标需求，标小兔，写标书，快如兔。

下载

import org.ehcache.Cache;
import org.ehcache.CacheManager;
import org.ehcache.config.builders.CacheConfigurationBuilder;
import org.ehcache.config.builders.CacheManagerBuilder;
import org.ehcache.config.builders.ResourcePoolsBuilder;
import org.ehcache.expiry.ExpiryPolicyBuilder;
import org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal;
import org.springframework.security.oauth2.server.resource.introspection.NimbusOpaqueTokenIntrospector;
import org.springframework.security.oauth2.server.resource.introspection.OpaqueTokenIntrospector;

import java.time.Duration;
import java.time.Instant;

public class CustomOpaqueTokenIntrospector implements OpaqueTokenIntrospector {

    private final OpaqueTokenIntrospector delegateIntrospector; // 委托给实际的内省器
    private final CacheManager cacheManager;
    private final Cache accessTokensCache;

    public CustomOpaqueTokenIntrospector(String uri, String clientId, String clientSecret) {
        // 1. 初始化Ehcache缓存管理器
        this.cacheManager = CacheManagerBuilder.newCacheManagerBuilder().build();
        this.cacheManager.init();

        // 2. 配置并创建缓存实例
        // 缓存名称为"iamCache"，键为String（token），值为OAuth2AuthenticatedPrincipal
        // 堆内存大小限制为1000个条目，过期策略为TTL（time-to-live）1800秒（30分钟）
        this.accessTokensCache = cacheManager.createCache("iamCache",
            CacheConfigurationBuilder
                .newCacheConfigurationBuilder(String.class, OAuth2AuthenticatedPrincipal.class,
                    ResourcePoolsBuilder.heap(1000))
                .withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofSeconds(1800))));

        // 3. 初始化委托的内省器，这里使用NimbusOpaqueTokenIntrospector
        this.delegateIntrospector = new NimbusOpaqueTokenIntrospector(uri, clientId, clientSecret);
    }

    @Override
    public OAuth2AuthenticatedPrincipal introspect(String token) {
        // 1. 尝试从缓存中获取令牌对应的认证主体
        OAuth2AuthenticatedPrincipal principal = accessTokensCache.get(token);

        if (principal != null) {
            // 2. 如果缓存中存在，检查其过期时间（"exp"属性）
            // 注意：这里假设OAuth2AuthenticatedPrincipal中包含"exp"属性，
            // 且其类型为Instant。实际应用中需根据认证服务器返回的内省结果调整。
            Instant expirationTime = principal.getAttribute("exp");
            if (expirationTime != null && expirationTime.isAfter(Instant.now())) {
                // 3. 如果未过期，直接返回缓存中的认证主体
                return principal;
            } else {
                // 4. 如果已过期，从缓存中移除
                accessTokensCache.remove(token);
            }
        }

        // 5. 如果缓存中不存在或已过期，调用委托的内省器进行实际的内省请求
        principal = delegateIntrospector.introspect(token);

        // 6. 将新的认证主体存入缓存
        accessTokensCache.put(token, principal);

        return principal;
    }

    /**
     * 提供一个方法用于获取缓存实例，尽管在实际生产代码中可能不需要直接暴露。
     * @return 缓存实例
     */
    public Cache getAccessTokensCache() {
        return accessTokensCache;
    }

    /**
     * 在应用程序关闭时，需要关闭CacheManager以释放资源。
     * 可以在Spring的@PreDestroy方法中调用此方法。
     */
    public void closeCacheManager() {
        if (cacheManager != null && cacheManager.getStatus() == org.ehcache.Status.AVAILABLE) {
            cacheManager.close();
        }
    }
}

代码解析：

• 构造函数：
  • 初始化CacheManager，它是Ehcache管理缓存的入口。
  • 通过CacheConfigurationBuilder配置并创建了一个名为iamCache的缓存。
    • ResourcePoolsBuilder.heap(1000)：指定缓存最大在堆内存中存储1000个条目。
    • withExpiry(ExpiryPolicyBuilder.timeToLiveExpiration(Duration.ofSeconds(1800)))：设置缓存条目的存活时间（TTL）为1800秒（30分钟）。这意味着一个条目在被添加到缓存后，最多存活30分钟。
  • 初始化delegateIntrospector，它是一个NimbusOpaqueTokenIntrospector实例，负责实际的远程内省调用。
• introspect(String token)方法：
  • 首先尝试从accessTokensCache中获取与token对应的OAuth2AuthenticatedPrincipal。
  • 如果找到，会检查其exp（过期时间）属性。如果exp存在且晚于当前时间，则认为令牌仍然有效，直接返回缓存中的principal。
  • 如果令牌已过期或在缓存中未找到，则调用delegateIntrospector.introspect(token)进行远程内省。
  • 内省成功后，将新的principal存入缓存，并返回。

3.2 将自定义内省器注册为Spring Bean

为了让Spring Security使用我们自定义的CustomOpaqueTokenIntrospector，我们需要在安全配置类中将其暴露为一个@Bean。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.oauth2.server.resource.introspection.OpaqueTokenIntrospector;
import org.springframework.beans.factory.annotation.Value;
import javax.annotation.PreDestroy; // 引入PreDestroy注解

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Value("${spring.security.oauth2.resourceserver.opaque-token.client-id}")
    private String clientId;
    @Value("${spring.security.oauth2.resourceserver.opaque-token.client-secret}")
    private String clientSecret;
    @Value("${spring.security.oauth2.resourceserver.opaque-token.introspection-uri}")
    private String introspectionUri;

    private CustomOpaqueTokenIntrospector customIntrospector; // 声明实例

    @Bean
    public OpaqueTokenIntrospector introspector() {
        // 创建并返回自定义的OpaqueTokenIntrospector实例
        this.customIntrospector = new CustomOpaqueTokenIntrospector(this.introspectionUri, this.clientId, this.clientSecret);
        return this.customIntrospector;
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests(authorizeRequests ->
                authorizeRequests
                    .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2ResourceServer ->
                oauth2ResourceServer
                    .opaqueToken(opaqueToken ->
                        // 将自定义的introspector Bean注入到Spring Security配置中
                        opaqueToken.introspector(introspector())
                    )
            );
    }

    // 在Bean销毁前关闭Ehcache CacheManager
    @PreDestroy
    public void destroy() {
        if (customIntrospector != null) {
            customIntrospector.closeCacheManager();
        }
    }
}

配置解析：

• @Bean public OpaqueTokenIntrospector introspector()：这个方法创建并返回CustomOpaqueTokenIntrospector的实例。Spring Security会自动检测到这个Bean，并将其用于不透明令牌的内省。
• opaqueToken.introspector(introspector())：明确告诉Spring Security使用我们提供的OpaqueTokenIntrospector Bean。
• @PreDestroy：在Spring容器销毁SecurityConfig Bean之前，调用closeCacheManager()方法，确保Ehcache资源得到正确释放，防止内存泄漏。

4. 注意事项与最佳实践

1. 依赖管理： 确保项目中已引入Ehcache的Maven或Gradle依赖：

   
   
       org.ehcache
       ehcache
       3.10.8 
   
   
       javax.xml.bind
       jaxb-api
       2.3.1 
   

2. 缓存过期策略：
   • TTL (Time To Live)： 从创建或最后一次更新开始计算的存活时间。
   • TTI (Time To Idle)： 从最后一次访问开始计算的空闲时间。
   • 选择合适的过期策略至关重要。通常，令牌的缓存过期时间应小于或等于令牌本身的实际过期时间，并考虑认证服务器的令牌刷新机制。本例中使用的是TTL。
3. 缓存容量与驱逐策略：
   • ResourcePoolsBuilder.heap(1000)：设置堆内存中缓存的最大条目数。当达到此限制时，Ehcache会根据配置的驱逐策略（如LRU、LFU等，默认通常是LRU）移除旧条目。
   • 生产环境中，应根据实际流量和内存情况调整缓存容量。
4. 分布式缓存：
   • 上述示例使用的是本地Ehcache，适用于单实例应用。
   • 如果应用部署在多个实例上，每个实例都会有自己的本地缓存，可能导致不同实例间数据不一致。
   • 对于分布式环境，应考虑使用Redis、Hazelcast等分布式缓存解决方案，并结合Spring Cache Abstraction进行更高级的抽象和管理。
5. 安全性： 缓存的令牌内省结果可能包含敏感信息。确保缓存存储在安全的环境中，并遵循最小权限原则。
6. 错误处理： 在introspect方法中，当delegateIntrospector.introspect(token)失败时（例如，认证服务器不可达），应考虑如何处理这些异常。是直接抛出异常，还是返回一个特定的错误主体，或者尝试重试？这取决于具体的业务需求和弹性策略。
7. Spring Cache Abstraction： 对于更通用的缓存需求，可以考虑使用Spring的@Cacheable、@CacheEvict等注解，并配置一个自定义的CacheManager。然而，对于OpaqueTokenIntrospector这种特定接口的包装，直接实现接口可能更直接。

5. 总结

通过自定义OpaqueTokenIntrospector并集成Ehcache，我们成功地为Spring Security OAuth2不透明令牌的内省请求引入了缓存机制。这不仅能有效减轻认证服务器的压力，提高资源服务器的性能和稳定性，还能在认证服务器暂时不可用时提供一定的容错能力。在实际部署时，务必根据应用场景和性能需求，合理配置缓存策略，并考虑分布式环境下的缓存解决方案。