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

本文旨在提供一个在Spring Security中缓存OAuth2不透明令牌内省请求的实用教程。当认证服务器不稳定时，通过自定义OpaqueTokenIntrospector并集成Ehcache等缓存机制，可以有效减少对认证服务器的请求次数，从而提高资源服务器的稳定性和响应速度，避免因内省失败导致的401错误。

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@EnableWebSecuritypublic 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实例。

PatentPal专利申请写作

AI软件来为专利申请自动生成内容

13 查看详情

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@EnableWebSecuritypublic 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. 注意事项与最佳实践

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

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

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

5. 总结

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

以上就是Spring Security OAuth2 不透明令牌内省请求缓存实战指南的详细内容，更多请关注创想鸟其它相关文章！