对于最新的稳定版本，请使用 Spring Security 6.5.3！spring-doc.cadn.net.cn

OAuth 2.0 资源服务器 JWT

JWT 的最小依赖关系

大多数资源服务器支持都收集到spring-security-oauth2-resource-server. 但是，对解码和验证 JWT 的支持是spring-security-oauth2-jose，这意味着两者都是必须的，才能拥有支持 JWT 编码的持有者Tokens的工作资源服务器。spring-doc.cadn.net.cn

JWT 的最小配置

使用 Spring Boot 时，将应用程序配置为资源服务器包括两个基本步骤。 首先，包括所需的依赖项。其次，标明授权服务器的位置。spring-doc.cadn.net.cn

指定授权服务器

在 Spring Boot 应用程序中，您需要指定要使用的授权服务器：spring-doc.cadn.net.cn

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com/issuer

哪里idp.example.com/issuer是iss授权服务器颁发的 JWT Tokens的声明。 此资源服务器使用此属性进一步自我配置，发现授权服务器的公钥，并随后验证传入的 JWT。spring-doc.cadn.net.cn

要使用issuer-uri属性，也必须是idp.example.com/issuer/.well-known/openid-configuration,idp.example.com/.well-known/openid-configuration/issuer或idp.example.com/.well-known/oauth-authorization-server/issuer是授权服务器支持的端点。 此终结点称为提供程序配置终结点或授权服务器元数据终结点。spring-doc.cadn.net.cn

创业期望

使用此属性和这些依赖项时，资源服务器会自动将自身配置为验证 JWT 编码的持有者Tokens。spring-doc.cadn.net.cn

它通过确定性启动过程实现这一点：spring-doc.cadn.net.cn

  1. 点击提供程序配置或授权服务器元数据端点，处理jwks_url财产。spring-doc.cadn.net.cn

  2. 配置验证策略以查询jwks_url用于有效的公用密钥。spring-doc.cadn.net.cn

  3. 配置验证策略以验证每个 JWTiss索赔idp.example.com.spring-doc.cadn.net.cn

此过程的结果是授权服务器必须接收请求才能使资源服务器成功启动。spring-doc.cadn.net.cn

如果授权服务器在资源服务器查询时关闭（给定适当的超时），则启动失败。spring-doc.cadn.net.cn

运行时预期

启动应用程序后，资源服务器会尝试处理包含Authorization: Bearer页眉：spring-doc.cadn.net.cn

GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this

只要指示此方案，资源服务器就会尝试根据持有者Tokens规范处理请求。spring-doc.cadn.net.cn

给定格式正确的 JWT，资源服务器：spring-doc.cadn.net.cn

  1. 根据从jwks_urlendpoint 并与 JWTs 标头匹配。spring-doc.cadn.net.cn

  2. 验证 JWTexp和nbf时间戳和 JWTiss索赔。spring-doc.cadn.net.cn

  3. 将每个范围映射到前缀为SCOPE_.spring-doc.cadn.net.cn

当授权服务器提供新密钥时，Spring Security会自动轮换用于验证JWTTokens的密钥。spring-doc.cadn.net.cn

默认情况下，生成的Authentication#getPrincipal是 Spring SecurityJwt对象，以及Authentication#getName映射到 JWT 的sub属性，如果存在的话。spring-doc.cadn.net.cn

从这里，考虑跳转到：spring-doc.cadn.net.cn

直接指定授权服务器 JWK 设置 URI

如果授权服务器不支持任何配置端点，或者如果资源服务器必须能够独立于授权服务器启动，则可以提供jwk-set-uri也：spring-doc.cadn.net.cn

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com
          jwk-set-uri: https://idp.example.com/.well-known/jwks.json

JWK Set uri 不是标准化的，但您通常可以在授权服务器的文档中找到它。spring-doc.cadn.net.cn

因此，资源服务器不会在启动时对授权服务器进行 ping作。 我们仍然指定issuer-uri以便资源服务器仍会验证iss对传入 JWT 的声明。spring-doc.cadn.net.cn

可以直接在 DSL 上提供此属性。spring-doc.cadn.net.cn

覆盖或替换引导自动配置

Spring Boot 生成两个@Bean代表资源服务器的对象。spring-doc.cadn.net.cn

第一个 bean 是一个SecurityWebFilterChain将应用程序配置为资源服务器。当包括spring-security-oauth2-jose这SecurityWebFilterChain看来：spring-doc.cadn.net.cn

资源服务器安全性WebFilterChain
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		.authorizeExchange(exchanges -> exchanges
			.anyExchange().authenticated()
		)
		.oauth2ResourceServer(OAuth2ResourceServerSpec::jwt)
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            jwt { }
        }
    }
}

如果应用程序未公开SecurityWebFilterChainbean，Spring Boot 公开默认的（如前面的列表所示）。spring-doc.cadn.net.cn

要替换它，请公开@Bean在应用程序中：spring-doc.cadn.net.cn

替换 SecurityWebFilterChain
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		.authorizeExchange(exchanges -> exchanges
			.pathMatchers("/message/**").hasAuthority("SCOPE_message:read")
			.anyExchange().authenticated()
		)
		.oauth2ResourceServer(oauth2 -> oauth2
			.jwt(withDefaults())
		);
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize("/message/**", hasAuthority("SCOPE_message:read"))
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            jwt { }
        }
    }
}

前面的配置需要message:read对于任何以/messages/.spring-doc.cadn.net.cn

方法oauth2ResourceServerDSL 也会覆盖或替换自动配置。spring-doc.cadn.net.cn

例如，第二个@BeanSpring Boot 创建的是一个ReactiveJwtDecoder，解码StringTokens转换为Jwt:spring-doc.cadn.net.cn

ReactiveJwt解码器
@Bean
public ReactiveJwtDecoder jwtDecoder() {
    return ReactiveJwtDecoders.fromIssuerLocation(issuerUri);
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return ReactiveJwtDecoders.fromIssuerLocation(issuerUri)
}

叫ReactiveJwtDecoders#fromIssuerLocation调用提供程序配置或授权服务器元数据端点以派生 JWK 集 URI。 如果应用程序未公开ReactiveJwtDecoderbean，Spring Boot 公开了上面默认的。spring-doc.cadn.net.cn

它的配置可以通过使用jwkSetUri()或替换为decoder().spring-doc.cadn.net.cn

用jwkSetUri()

您可以将授权服务器的 JWK Set URI 配置为配置属性，或在 DSL 中提供它：spring-doc.cadn.net.cn

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		.authorizeExchange(exchanges -> exchanges
			.anyExchange().authenticated()
		)
		.oauth2ResourceServer(oauth2 -> oauth2
			.jwt(jwt -> jwt
				.jwkSetUri("https://idp.example.com/.well-known/jwks.json")
			)
		);
	return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            jwt {
                jwkSetUri = "https://idp.example.com/.well-known/jwks.json"
            }
        }
    }
}

用jwkSetUri()优先于任何配置属性。spring-doc.cadn.net.cn

用decoder()

decoder()比jwkSetUri()，因为它完全取代了JwtDecoder:spring-doc.cadn.net.cn

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		.authorizeExchange(exchanges -> exchanges
			.anyExchange().authenticated()
		)
		.oauth2ResourceServer(oauth2 -> oauth2
			.jwt(jwt -> jwt
				.decoder(myCustomDecoder())
			)
		);
    return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            jwt {
                jwtDecoder = myCustomDecoder()
            }
        }
    }
}

当您需要更深入的配置（例如验证）时，这很方便。spring-doc.cadn.net.cn

公开ReactiveJwtDecoder @Bean

或者，公开ReactiveJwtDecoder @Bean具有与decoder():spring-doc.cadn.net.cn

@Bean
public ReactiveJwtDecoder jwtDecoder() {
    return NimbusReactiveJwtDecoder.withJwkSetUri(jwkSetUri).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return ReactiveJwtDecoders.fromIssuerLocation(issuerUri)
}

配置可信算法

默认情况下，NimbusReactiveJwtDecoder，因此资源服务器，仅信任和验证使用RS256.spring-doc.cadn.net.cn

您可以使用 Spring Boot 或使用 NimbusJwtDecoder 构建器自定义此行为。spring-doc.cadn.net.cn

使用 Spring Boot 自定义可信算法

设置算法的最简单方法是作为属性：spring-doc.cadn.net.cn

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jws-algorithm: RS512
          jwk-set-uri: https://idp.example.org/.well-known/jwks.json

使用构建器自定义可信算法

不过，为了获得更大的功能，我们可以使用附带的构建器NimbusReactiveJwtDecoder:spring-doc.cadn.net.cn

@Bean
ReactiveJwtDecoder jwtDecoder() {
    return NimbusReactiveJwtDecoder.withJwkSetUri(this.jwkSetUri)
            .jwsAlgorithm(RS512).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return NimbusReactiveJwtDecoder.withJwkSetUri(this.jwkSetUri)
            .jwsAlgorithm(RS512).build()
}

叫jwsAlgorithm多次配置NimbusReactiveJwtDecoder要信任多个算法：spring-doc.cadn.net.cn

@Bean
ReactiveJwtDecoder jwtDecoder() {
    return NimbusReactiveJwtDecoder.withJwkSetUri(this.jwkSetUri)
            .jwsAlgorithm(RS512).jwsAlgorithm(ES512).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return NimbusReactiveJwtDecoder.withJwkSetUri(this.jwkSetUri)
            .jwsAlgorithm(RS512).jwsAlgorithm(ES512).build()
}

或者，您可以调用jwsAlgorithms:spring-doc.cadn.net.cn

@Bean
ReactiveJwtDecoder jwtDecoder() {
    return NimbusReactiveJwtDecoder.withJwkSetUri(this.jwkSetUri)
            .jwsAlgorithms(algorithms -> {
                    algorithms.add(RS512);
                    algorithms.add(ES512);
            }).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return NimbusReactiveJwtDecoder.withJwkSetUri(this.jwkSetUri)
            .jwsAlgorithms {
                it.add(RS512)
                it.add(ES512)
            }
            .build()
}

信任单个非对称密钥

比使用 JWK 集端点支持资源服务器更简单的方法是对 RSA 公钥进行硬编码。 公用密钥可以通过 Spring Boot 或通过使用 Builder 提供。spring-doc.cadn.net.cn

通过 Spring Boot

您可以使用 Spring Boot 指定密钥：spring-doc.cadn.net.cn

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          public-key-location: classpath:my-key.pub

或者，为了允许更复杂的查找，您可以对RsaKeyConversionServicePostProcessor:spring-doc.cadn.net.cn

BeanFactory后处理器
@Bean
BeanFactoryPostProcessor conversionServiceCustomizer() {
    return beanFactory ->
        beanFactory.getBean(RsaKeyConversionServicePostProcessor.class)
                .setResourceLoader(new CustomResourceLoader());
}
@Bean
fun conversionServiceCustomizer(): BeanFactoryPostProcessor {
    return BeanFactoryPostProcessor { beanFactory: ConfigurableListableBeanFactory ->
        beanFactory.getBean<RsaKeyConversionServicePostProcessor>()
                .setResourceLoader(CustomResourceLoader())
    }
}

指定密钥的位置：spring-doc.cadn.net.cn

key.location: hfds://my-key.pub

然后自动连接值：spring-doc.cadn.net.cn

@Value("${key.location}")
RSAPublicKey key;
@Value("\${key.location}")
val key: RSAPublicKey? = null

使用构建器

要连接RSAPublicKey直接，使用适当的NimbusReactiveJwtDecoder架构工人：spring-doc.cadn.net.cn

@Bean
public ReactiveJwtDecoder jwtDecoder() {
    return NimbusReactiveJwtDecoder.withPublicKey(this.key).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return NimbusReactiveJwtDecoder.withPublicKey(key).build()
}

信任单个对称密钥

您还可以使用单个对称键。 您可以加载您的SecretKey并使用适当的NimbusReactiveJwtDecoder架构工人：spring-doc.cadn.net.cn

@Bean
public ReactiveJwtDecoder jwtDecoder() {
    return NimbusReactiveJwtDecoder.withSecretKey(this.key).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    return NimbusReactiveJwtDecoder.withSecretKey(this.key).build()
}

配置授权

从 OAuth 2.0 授权服务器颁发的 JWT 通常具有scope或scp属性，指示它已被授予的作用域（或权限）——例如：spring-doc.cadn.net.cn

{ ..., "scope" : "messages contacts"}

在这种情况下，资源服务器会尝试将这些作用域强制到已授予权限的列表中，并在每个作用域前面加上字符串SCOPE_.spring-doc.cadn.net.cn

这意味着，要保护作用域派生自 JWT 的端点或方法，相应的表达式应包含以下前缀：spring-doc.cadn.net.cn

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		.authorizeExchange(exchanges -> exchanges
			.mvcMatchers("/contacts/**").hasAuthority("SCOPE_contacts")
			.mvcMatchers("/messages/**").hasAuthority("SCOPE_messages")
			.anyExchange().authenticated()
		)
		.oauth2ResourceServer(OAuth2ResourceServerSpec::jwt);
    return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize("/contacts/**", hasAuthority("SCOPE_contacts"))
            authorize("/messages/**", hasAuthority("SCOPE_messages"))
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            jwt { }
        }
    }
}

您可以对方法安全性执行类似的作：spring-doc.cadn.net.cn

@PreAuthorize("hasAuthority('SCOPE_messages')")
public Flux<Message> getMessages(...) {}
@PreAuthorize("hasAuthority('SCOPE_messages')")
fun getMessages(): Flux<Message> { }

手动提取权限

但是，在许多情况下，这种默认值是不够的。 例如，某些授权服务器不使用scope属性。相反，它们有自己的自定义属性。 在其他时候，资源服务器可能需要将属性或属性组合调整为内部化权限。spring-doc.cadn.net.cn

为此，DSL 公开了jwtAuthenticationConverter():spring-doc.cadn.net.cn

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		.authorizeExchange(exchanges -> exchanges
			.anyExchange().authenticated()
		)
		.oauth2ResourceServer(oauth2 -> oauth2
			.jwt(jwt -> jwt
				.jwtAuthenticationConverter(grantedAuthoritiesExtractor())
			)
		);
	return http.build();
}

Converter<Jwt, Mono<AbstractAuthenticationToken>> grantedAuthoritiesExtractor() {
    JwtAuthenticationConverter jwtAuthenticationConverter =
            new JwtAuthenticationConverter();
    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter
            (new GrantedAuthoritiesExtractor());
    return new ReactiveJwtAuthenticationConverterAdapter(jwtAuthenticationConverter);
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
    return http {
        authorizeExchange {
            authorize(anyExchange, authenticated)
        }
        oauth2ResourceServer {
            jwt {
                jwtAuthenticationConverter = grantedAuthoritiesExtractor()
            }
        }
    }
}

fun grantedAuthoritiesExtractor(): Converter<Jwt, Mono<AbstractAuthenticationToken>> {
    val jwtAuthenticationConverter = JwtAuthenticationConverter()
    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(GrantedAuthoritiesExtractor())
    return ReactiveJwtAuthenticationConverterAdapter(jwtAuthenticationConverter)
}

jwtAuthenticationConverter()负责将Jwt变成一个Authentication. 作为其配置的一部分，我们可以提供一个辅助转换器，以便从Jwt设置为Collection授予的权力。spring-doc.cadn.net.cn

最终转换器可能类似于以下内容GrantedAuthoritiesExtractor:spring-doc.cadn.net.cn

static class GrantedAuthoritiesExtractor
        implements Converter<Jwt, Collection<GrantedAuthority>> {

    public Collection<GrantedAuthority> convert(Jwt jwt) {
        Collection<?> authorities = (Collection<?>)
                jwt.getClaims().getOrDefault("mycustomclaim", Collections.emptyList());

        return authorities.stream()
                .map(Object::toString)
                .map(SimpleGrantedAuthority::new)
                .collect(Collectors.toList());
    }
}
internal class GrantedAuthoritiesExtractor : Converter<Jwt, Collection<GrantedAuthority>> {
    override fun convert(jwt: Jwt): Collection<GrantedAuthority> {
        val authorities: List<Any> = jwt.claims
                .getOrDefault("mycustomclaim", emptyList<Any>()) as List<Any>
        return authorities
                .map { it.toString() }
                .map { SimpleGrantedAuthority(it) }
    }
}

为了获得更大的灵活性，DSL 支持将转换器完全替换为实现Converter<Jwt, Mono<AbstractAuthenticationToken>>:spring-doc.cadn.net.cn

static class CustomAuthenticationConverter implements Converter<Jwt, Mono<AbstractAuthenticationToken>> {
    public AbstractAuthenticationToken convert(Jwt jwt) {
        return Mono.just(jwt).map(this::doConversion);
    }
}
internal class CustomAuthenticationConverter : Converter<Jwt, Mono<AbstractAuthenticationToken>> {
    override fun convert(jwt: Jwt): Mono<AbstractAuthenticationToken> {
        return Mono.just(jwt).map(this::doConversion)
    }
}

配置验证

使用最少的 Spring Boot 配置，指示授权服务器的颁发者 URI，资源服务器默认验证issclaim 以及exp和nbftimestamp 声明。spring-doc.cadn.net.cn

在需要自定义验证需求的情况下，资源服务器附带两个标准验证器，并且还接受自定义OAuth2TokenValidator实例。spring-doc.cadn.net.cn

自定义时间戳验证

JWT 实例通常有一个有效窗口，窗口的开始在nbfclaim 和exp索赔。spring-doc.cadn.net.cn

但是，每台服务器都可能遇到时钟漂移，这可能导致Tokens在一台服务器上似乎已过期，但在另一台服务器上却没有。 这可能会导致一些实施胃灼热，因为分布式系统中协作服务器的数量会增加。spring-doc.cadn.net.cn

资源服务器使用JwtTimestampValidator以验证Tokens的有效性窗口，您可以使用clockSkew要缓解时钟漂移问题：spring-doc.cadn.net.cn

@Bean
ReactiveJwtDecoder jwtDecoder() {
     NimbusReactiveJwtDecoder jwtDecoder = (NimbusReactiveJwtDecoder)
             ReactiveJwtDecoders.fromIssuerLocation(issuerUri);

     OAuth2TokenValidator<Jwt> withClockSkew = new DelegatingOAuth2TokenValidator<>(
            new JwtTimestampValidator(Duration.ofSeconds(60)),
            new IssuerValidator(issuerUri));

     jwtDecoder.setJwtValidator(withClockSkew);

     return jwtDecoder;
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    val jwtDecoder = ReactiveJwtDecoders.fromIssuerLocation(issuerUri) as NimbusReactiveJwtDecoder
    val withClockSkew: OAuth2TokenValidator<Jwt> = DelegatingOAuth2TokenValidator(
            JwtTimestampValidator(Duration.ofSeconds(60)),
            JwtIssuerValidator(issuerUri))
    jwtDecoder.setJwtValidator(withClockSkew)
    return jwtDecoder
}

默认情况下，资源服务器将时钟偏差配置为 60 秒。spring-doc.cadn.net.cn

配置自定义验证器

您可以为aud声明与OAuth2TokenValidator应用程序接口：spring-doc.cadn.net.cn

public class AudienceValidator implements OAuth2TokenValidator<Jwt> {
    OAuth2Error error = new OAuth2Error("invalid_token", "The required audience is missing", null);

    public OAuth2TokenValidatorResult validate(Jwt jwt) {
        if (jwt.getAudience().contains("messaging")) {
            return OAuth2TokenValidatorResult.success();
        } else {
            return OAuth2TokenValidatorResult.failure(error);
        }
    }
}
class AudienceValidator : OAuth2TokenValidator<Jwt> {
    var error: OAuth2Error = OAuth2Error("invalid_token", "The required audience is missing", null)
    override fun validate(jwt: Jwt): OAuth2TokenValidatorResult {
        return if (jwt.audience.contains("messaging")) {
            OAuth2TokenValidatorResult.success()
        } else {
            OAuth2TokenValidatorResult.failure(error)
        }
    }
}

然后，要添加到资源服务器中，您可以指定ReactiveJwtDecoder实例：spring-doc.cadn.net.cn

@Bean
ReactiveJwtDecoder jwtDecoder() {
    NimbusReactiveJwtDecoder jwtDecoder = (NimbusReactiveJwtDecoder)
            ReactiveJwtDecoders.fromIssuerLocation(issuerUri);

    OAuth2TokenValidator<Jwt> audienceValidator = new AudienceValidator();
    OAuth2TokenValidator<Jwt> withIssuer = JwtValidators.createDefaultWithIssuer(issuerUri);
    OAuth2TokenValidator<Jwt> withAudience = new DelegatingOAuth2TokenValidator<>(withIssuer, audienceValidator);

    jwtDecoder.setJwtValidator(withAudience);

    return jwtDecoder;
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
    val jwtDecoder = ReactiveJwtDecoders.fromIssuerLocation(issuerUri) as NimbusReactiveJwtDecoder
    val audienceValidator: OAuth2TokenValidator<Jwt> = AudienceValidator()
    val withIssuer: OAuth2TokenValidator<Jwt> = JwtValidators.createDefaultWithIssuer(issuerUri)
    val withAudience: OAuth2TokenValidator<Jwt> = DelegatingOAuth2TokenValidator(withIssuer, audienceValidator)
    jwtDecoder.setJwtValidator(withAudience)
    return jwtDecoder
}