OAuth 2.0 资源服务器 JWT

JWT 的最少依赖

大多数资源服务器的支持都收集在 spring-security-oauth2-resource-server 中。然而，解码和验证 JWT 的支持在 spring-security-oauth2-jose 中，这意味着两者都是拥有一个支持 JWT 编码的 Bearer 令牌的正常工作的资源服务器所必需的。

JWT 的最少配置

使用 Spring Boot 时，将应用程序配置为资源服务器包含两个基本步骤。首先，包含所需的依赖项，其次，指明授权服务器的位置。

指定授权服务器

在 Spring Boot 应用程序中，要指定使用哪个授权服务器，只需执行以下操作：

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

其中 idp.example.com/issuer 是授权服务器将颁发的 JWT 令牌中 iss 声明的值。资源服务器将使用此属性进一步自行配置、发现授权服务器的公钥，并随后验证传入的 JWT。

要使用 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。此端点称为提供商配置 (Provider Configuration) 端点或授权服务器元数据 (Authorization Server Metadata) 端点。

就这样！

启动期望

使用此属性和这些依赖项时，资源服务器将自动配置自身以验证 JWT 编码的 Bearer 令牌。

它通过确定性的启动过程实现此目的：

查询提供商配置或授权服务器元数据端点以获取 jwks_url 属性
查询 jwks_url 端点以获取支持的算法
配置验证策略以查询 jwks_url 以获取找到的算法的有效公钥
配置验证策略以针对 idp.example.com 验证每个 JWT 的 iss 声明。

此过程的一个结果是，授权服务器必须启动并接收请求，资源服务器才能成功启动。

如果在资源服务器查询授权服务器时（给定适当的超时时间）授权服务器宕机，则启动将失败。

运行时期望

应用程序启动后，资源服务器将尝试处理包含 Authorization: Bearer 头的任何请求

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

只要指明了此方案，资源服务器将尝试根据 Bearer 令牌规范处理请求。

给定一个格式正确的 JWT，资源服务器将：

根据启动期间从 jwks_url 端点获取并与 JWT 匹配的公钥验证其签名
验证 JWT 的 exp 和 nbf 时间戳以及 JWT 的 iss 声明，并且
将每个范围映射到带有前缀 SCOPE_ 的权限。

随着授权服务器提供新密钥，Spring Security 将自动轮换用于验证 JWT 的密钥。

默认情况下，生成的 Authentication#getPrincipal 是一个 Spring Security Jwt 对象，如果存在，Authentication#getName 将映射到 JWT 的 sub 属性。

从这里，可以考虑跳转到：

JWT 认证如何工作
如何在不将资源服务器启动与授权服务器可用性绑定在一起的情况下进行配置
如何在不使用 Spring Boot 的情况下进行配置

JWT 认证如何工作

接下来，让我们看看 Spring Security 用于支持 servlet 应用程序（例如我们刚刚看到的应用程序）中 JWT 认证的架构组件。

JwtAuthenticationProvider 是一个 AuthenticationProvider 实现，它利用 JwtDecoder 和 JwtAuthenticationConverter 来认证 JWT。

让我们看看 JwtAuthenticationProvider 在 Spring Security 中如何工作。下图解释了从读取 Bearer 令牌图中的 AuthenticationManager 的工作细节。

图 1. JwtAuthenticationProvider 用法

number 1 来自读取 Bearer 令牌的认证 Filter 将 BearerTokenAuthenticationToken 传递给由 ProviderManager 实现的 AuthenticationManager。

number 2 ProviderManager 配置为使用类型为 JwtAuthenticationProvider 的 AuthenticationProvider。

number 3 JwtAuthenticationProvider 使用 JwtDecoder 解码、验证和校验 Jwt。

number 4 然后 JwtAuthenticationProvider 使用 JwtAuthenticationConverter 将 Jwt 转换为授予权限的 Collection。

number 5 认证成功时，返回的 Authentication 类型为 JwtAuthenticationToken，其 principal 是由配置的 JwtDecoder 返回的 Jwt。最终，返回的 JwtAuthenticationToken 将由认证 Filter 设置到 SecurityContextHolder 上。

直接指定授权服务器 JWK Set Uri

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

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 未标准化，但通常可以在授权服务器的文档中找到

因此，资源服务器启动时不会 ping 授权服务器。我们仍然指定 issuer-uri，以便资源服务器仍然验证传入 JWT 上的 iss 声明。

此属性也可以直接在 DSL 上提供。

提供 Audience

如前所述，issuer-uri 属性验证 iss 声明；这是指谁发送了 JWT。

Boot 还具有 audiences 属性，用于验证 aud 声明；这是指 JWT 被发送给了谁。

资源服务器的 audience 可以如下所示指定：

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://idp.example.com
          audiences: https://my-resource-server.example.com

如果需要，您还可以以编程方式添加 aud 验证。

结果是，如果 JWT 的 iss 声明不是 idp.example.com，并且其 aud 声明列表中不包含 my-resource-server.example.com，则验证将失败。

覆盖或替换 Boot 自动配置

Spring Boot 代表资源服务器生成了两个 @Bean。

第一个是 SecurityFilterChain，它将应用程序配置为资源服务器。包含 spring-security-oauth2-jose 时，此 SecurityFilterChain 如下所示：

默认 JWT 配置

Java
Kotlin

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .authorizeHttpRequests(authorize -> authorize
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer((oauth2) -> oauth2.jwt(Customizer.withDefaults()));
    return http.build();
}

@Bean
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
    http {
        authorizeRequests {
            authorize(anyRequest, authenticated)
        }
        oauth2ResourceServer {
            jwt { }
        }
    }
    return http.build()
}

如果应用程序未暴露 SecurityFilterChain bean，则 Spring Boot 将暴露上述默认 bean。

替换它就像在应用程序中暴露 bean 一样简单：

自定义 JWT 配置

Java
Kotlin

import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
public class MyCustomSecurityConfiguration {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/messages/**").access(hasScope("message:read"))
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(myConverter())
                )
            );
        return http.build();
    }
}

import org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope

@Configuration
@EnableWebSecurity
class MyCustomSecurityConfiguration {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize("/messages/**", hasScope("message:read"))
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                jwt {
                    jwtAuthenticationConverter = myConverter()
                }
            }
        }
        return http.build()
    }
}

以上配置要求任何以 /messages/ 开头的 URL 具有 message:read 范围。

oauth2ResourceServer DSL 上的方法也将覆盖或替换自动配置。

例如，Spring Boot 创建的第二个 @Bean 是 JwtDecoder，它将 String 令牌解码为经过验证的 Jwt 实例

JWT 解码器

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder() {
    return JwtDecoders.fromIssuerLocation(issuerUri);
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return JwtDecoders.fromIssuerLocation(issuerUri)
}

调用 JwtDecoders#fromIssuerLocation 会调用提供商配置或授权服务器元数据端点，以便派生 JWK Set Uri。

如果应用程序未暴露 JwtDecoder bean，则 Spring Boot 将暴露上述默认 bean。

其配置可以使用 jwkSetUri() 进行覆盖，或使用 decoder() 进行替换。

或者，如果您根本不使用 Spring Boot，那么这两个组件——过滤链和 JwtDecoder——都可以在 XML 中指定。

过滤链如下指定：

默认 JWT 配置

<http>
    <intercept-uri pattern="/**" access="authenticated"/>
    <oauth2-resource-server>
        <jwt decoder-ref="jwtDecoder"/>
    </oauth2-resource-server>
</http>

JwtDecoder 如下指定：

JWT 解码器

<bean id="jwtDecoder"
        class="org.springframework.security.oauth2.jwt.JwtDecoders"
        factory-method="fromIssuerLocation">
    <constructor-arg value="${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}"/>
</bean>

使用 `jwkSetUri()`

授权服务器的 JWK Set Uri 可以配置为配置属性，也可以在 DSL 中提供

JWK Set Uri 配置

Java
Kotlin
Xml

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredJwkSetUri {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwkSetUri("https://idp.example.com/.well-known/jwks.json")
                )
            );
        return http.build();
    }
}

@Configuration
@EnableWebSecurity
class DirectlyConfiguredJwkSetUri {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                jwt {
                    jwkSetUri = "https://idp.example.com/.well-known/jwks.json"
                }
            }
        }
        return http.build()
    }
}

<http>
    <intercept-uri pattern="/**" access="authenticated"/>
    <oauth2-resource-server>
        <jwt jwk-set-uri="https://idp.example.com/.well-known/jwks.json"/>
    </oauth2-resource-server>
</http>

使用 jwkSetUri() 优先于任何配置属性。

使用 `decoder()`

比 jwkSetUri() 更强大的是 decoder()，它将完全替换 JwtDecoder 的任何 Boot 自动配置

JWT 解码器配置

Java
Kotlin
Xml

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredJwtDecoder {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .decoder(myCustomDecoder())
                )
            );
        return http.build();
    }
}

@Configuration
@EnableWebSecurity
class DirectlyConfiguredJwtDecoder {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                jwt {
                    jwtDecoder = myCustomDecoder()
                }
            }
        }
        return http.build()
    }
}

<http>
    <intercept-uri pattern="/**" access="authenticated"/>
    <oauth2-resource-server>
        <jwt decoder-ref="myCustomDecoder"/>
    </oauth2-resource-server>
</http>

当需要更深入的配置（例如验证、映射或请求超时）时，这非常方便。

暴露 `JwtDecoder` `@Bean`

或者，暴露一个 JwtDecoder @Bean 与 decoder() 具有相同的效果。您可以像这样构造一个带有 jwkSetUri 的实例：

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withJwkSetUri(jwkSetUri).build()
}

或者您可以使用 issuer 并让 NimbusJwtDecoder 在调用 build() 时查找 jwkSetUri，如下所示：

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withIssuerLocation(issuer).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withIssuerLocation(issuer).build()
}

或者，如果默认配置适合您，您也可以使用 JwtDecoders，它除了配置解码器的 validator 外，还执行上述操作

Java
Kotlin

@Bean
public JwtDecoders jwtDecoder() {
    return JwtDecoders.fromIssuerLocation(issuer);
}

@Bean
fun jwtDecoder(): JwtDecoders {
    return JwtDecoders.fromIssuerLocation(issuer)
}

配置可信算法

默认情况下，NimbusJwtDecoder 以及资源服务器，将仅使用 RS256 信任和验证令牌。

您可以通过 Spring Boot、NimbusJwtDecoder 构建器或从 JWK Set 响应来自定义此设置。

通过 Spring Boot

设置算法最简单的方法是将其作为一个属性：

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

使用构建器

但是，为了获得更大的能力，我们可以使用随 NimbusJwtDecoder 附带的构建器

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withIssuerLocation(this.issuer)
            .jwsAlgorithm(RS512).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withIssuerLocation(this.issuer)
            .jwsAlgorithm(RS512).build()
}

多次调用 jwsAlgorithm 将配置 NimbusJwtDecoder 信任多种算法，如下所示：

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withIssuerLocation(this.issuer)
            .jwsAlgorithm(RS512).jwsAlgorithm(ES512).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withIssuerLocation(this.issuer)
            .jwsAlgorithm(RS512).jwsAlgorithm(ES512).build()
}

或者，您可以调用 jwsAlgorithms

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withIssuerLocation(this.issuer)
            .jwsAlgorithms(algorithms -> {
                    algorithms.add(RS512);
                    algorithms.add(ES512);
            }).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withIssuerLocation(this.issuer)
            .jwsAlgorithms {
                it.add(RS512)
                it.add(ES512)
            }.build()
}

从 JWK Set 响应

由于 Spring Security 的 JWT 支持基于 Nimbus，您也可以使用它的所有强大特性。

例如，Nimbus 有一个 JWSKeySelector 实现，它将根据 JWK Set URI 响应选择一组算法。您可以像这样使用它来生成 NimbusJwtDecoder：

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder() {
    // makes a request to the JWK Set endpoint
    JWSKeySelector<SecurityContext> jwsKeySelector =
            JWSAlgorithmFamilyJWSKeySelector.fromJWKSetURL(this.jwkSetUrl);

    DefaultJWTProcessor<SecurityContext> jwtProcessor =
            new DefaultJWTProcessor<>();
    jwtProcessor.setJWSKeySelector(jwsKeySelector);

    return new NimbusJwtDecoder(jwtProcessor);
}

@Bean
fun jwtDecoder(): JwtDecoder {
    // makes a request to the JWK Set endpoint
    val jwsKeySelector: JWSKeySelector<SecurityContext> = JWSAlgorithmFamilyJWSKeySelector.fromJWKSetURL<SecurityContext>(this.jwkSetUrl)
    val jwtProcessor: DefaultJWTProcessor<SecurityContext> = DefaultJWTProcessor()
    jwtProcessor.jwsKeySelector = jwsKeySelector
    return NimbusJwtDecoder(jwtProcessor)
}

信任单个非对称密钥

比使用 JWK Set 端点支持资源服务器更简单的方法是硬编码一个 RSA 公钥。公钥可以通过 Spring Boot 或使用构建器提供。

通过 Spring Boot

通过 Spring Boot 指定密钥非常简单。密钥的位置可以如下指定：

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

或者，为了实现更复杂的查找，您可以后处理 RsaKeyConversionServicePostProcessor

Java
Kotlin

@Bean
BeanFactoryPostProcessor conversionServiceCustomizer() {
    return beanFactory ->
        beanFactory.getBean(RsaKeyConversionServicePostProcessor.class)
                .setResourceLoader(new CustomResourceLoader());
}

@Bean
fun conversionServiceCustomizer(): BeanFactoryPostProcessor {
    return BeanFactoryPostProcessor { beanFactory ->
        beanFactory.getBean<RsaKeyConversionServicePostProcessor>()
                .setResourceLoader(CustomResourceLoader())
    }
}

指定您的密钥位置

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

然后自动装配该值

Java
Kotlin

@Value("${key.location}")
RSAPublicKey key;

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

使用构建器

要直接注入一个 RSAPublicKey，您只需使用相应的 NimbusJwtDecoder 构建器，如下所示：

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withPublicKey(this.key).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withPublicKey(this.key).build()
}

信任单个对称密钥

使用单个对称密钥也很简单。您只需加载您的 SecretKey 并使用相应的 NimbusJwtDecoder 构建器，如下所示：

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder() {
    return NimbusJwtDecoder.withSecretKey(this.key).build();
}

@Bean
fun jwtDecoder(): JwtDecoder {
    return NimbusJwtDecoder.withSecretKey(key).build()
}

配置授权

从 OAuth 2.0 授权服务器颁发的 JWT 通常会包含 scope 或 scp 属性，指示已授予的范围（或权限），例如：

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

在这种情况下，资源服务器将尝试将这些范围强制转换为授予权限列表，并在每个范围前加上字符串 "SCOPE_"。

这意味着要使用从 JWT 派生的范围保护端点或方法，相应的表达式应包含此前缀

授权配置

Java
Kotlin
Xml

import static org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
public class DirectlyConfiguredJwkSetUri {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/contacts/**").access(hasScope("contacts"))
                .requestMatchers("/messages/**").access(hasScope("messages"))
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(Customizer.withDefaults())
            );
        return http.build();
    }
}

import org.springframework.security.oauth2.core.authorization.OAuth2AuthorizationManagers.hasScope;

@Configuration
@EnableWebSecurity
class DirectlyConfiguredJwkSetUri {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeRequests {
                authorize("/contacts/**", hasScope("contacts"))
                authorize("/messages/**", hasScope("messages"))
                authorize(anyRequest, authenticated)
            }
            oauth2ResourceServer {
                jwt { }
            }
        }
        return http.build()
    }
}

<http>
    <intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
    <intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
    <oauth2-resource-server>
        <jwt jwk-set-uri="https://idp.example.org/.well-known/jwks.json"/>
    </oauth2-resource-server>
</http>

或者类似地应用于方法安全：

Java
Kotlin

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

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

手动提取权限

然而，在许多情况下，此默认设置不足够。例如，一些授权服务器不使用 scope 属性，而是使用自己的自定义属性。或者，在其他时候，资源服务器可能需要将属性或属性的组合转换为内部化的权限。

为此，Spring Security 附带了 JwtAuthenticationConverter，它负责将 Jwt 转换为 Authentication。默认情况下，Spring Security 会使用 JwtAuthenticationConverter 的默认实例来配置 JwtAuthenticationProvider。

作为配置 JwtAuthenticationConverter 的一部分，您可以提供一个辅助转换器，用于将 Jwt 转换为授予权限的 Collection。

假设您的授权服务器在名为 authorities 的自定义声明中通信权限。在这种情况下，您可以配置 JwtAuthenticationConverter 应该检查的声明，如下所示：

权限声明配置

Java
Kotlin
Xml

@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
    grantedAuthoritiesConverter.setAuthoritiesClaimName("authorities");

    JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
    return jwtAuthenticationConverter;
}

@Bean
fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
    val grantedAuthoritiesConverter = JwtGrantedAuthoritiesConverter()
    grantedAuthoritiesConverter.setAuthoritiesClaimName("authorities")

    val jwtAuthenticationConverter = JwtAuthenticationConverter()
    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter)
    return jwtAuthenticationConverter
}

<http>
    <intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
    <intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
    <oauth2-resource-server>
        <jwt jwk-set-uri="https://idp.example.org/.well-known/jwks.json"
                jwt-authentication-converter-ref="jwtAuthenticationConverter"/>
    </oauth2-resource-server>
</http>

<bean id="jwtAuthenticationConverter"
        class="org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter">
    <property name="jwtGrantedAuthoritiesConverter" ref="jwtGrantedAuthoritiesConverter"/>
</bean>

<bean id="jwtGrantedAuthoritiesConverter"
        class="org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter">
    <property name="authoritiesClaimName" value="authorities"/>
</bean>

您还可以配置不同的权限前缀。您可以将其从在每个权限前加上 SCOPE_ 更改为加上 ROLE_，如下所示：

权限前缀配置

Java
Kotlin
Xml

@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
    grantedAuthoritiesConverter.setAuthorityPrefix("ROLE_");

    JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
    return jwtAuthenticationConverter;
}

@Bean
fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
    val grantedAuthoritiesConverter = JwtGrantedAuthoritiesConverter()
    grantedAuthoritiesConverter.setAuthorityPrefix("ROLE_")

    val jwtAuthenticationConverter = JwtAuthenticationConverter()
    jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter)
    return jwtAuthenticationConverter
}

<http>
    <intercept-uri pattern="/contacts/**" access="hasAuthority('SCOPE_contacts')"/>
    <intercept-uri pattern="/messages/**" access="hasAuthority('SCOPE_messages')"/>
    <oauth2-resource-server>
        <jwt jwk-set-uri="https://idp.example.org/.well-known/jwks.json"
                jwt-authentication-converter-ref="jwtAuthenticationConverter"/>
    </oauth2-resource-server>
</http>

<bean id="jwtAuthenticationConverter"
        class="org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter">
    <property name="jwtGrantedAuthoritiesConverter" ref="jwtGrantedAuthoritiesConverter"/>
</bean>

<bean id="jwtGrantedAuthoritiesConverter"
        class="org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter">
    <property name="authorityPrefix" value="ROLE_"/>
</bean>

或者，您可以完全移除前缀，通过调用 JwtGrantedAuthoritiesConverter#setAuthorityPrefix("")。

为了获得更大的灵活性，DSL 支持将转换器完全替换为实现 Converter<Jwt, AbstractAuthenticationToken> 的任何类

Java
Kotlin

static class CustomAuthenticationConverter implements Converter<Jwt, AbstractAuthenticationToken> {
    public AbstractAuthenticationToken convert(Jwt jwt) {
        return new CustomAuthenticationToken(jwt);
    }
}

// ...

@Configuration
@EnableWebSecurity
public class CustomAuthenticationConverterConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(new CustomAuthenticationConverter())
                )
            );
        return http.build();
    }
}

internal class CustomAuthenticationConverter : Converter<Jwt, AbstractAuthenticationToken> {
    override fun convert(jwt: Jwt): AbstractAuthenticationToken {
        return CustomAuthenticationToken(jwt)
    }
}

// ...

@Configuration
@EnableWebSecurity
class CustomAuthenticationConverterConfig {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
       http {
            authorizeRequests {
                authorize(anyRequest, authenticated)
            }
           oauth2ResourceServer {
               jwt {
                   jwtAuthenticationConverter = CustomAuthenticationConverter()
               }
           }
        }
        return http.build()
    }
}

配置验证

使用最少的 Spring Boot 配置，指示授权服务器的 issuer uri，资源服务器将默认验证 iss 声明以及 exp 和 nbf 时间戳声明。

在需要自定义验证的情况下，资源服务器提供了两个标准 validator，并且也接受自定义的 OAuth2TokenValidator 实例。

自定义时间戳验证

JWT 通常有一个有效期窗口，窗口的开始由 nbf 声明指示，结束由 exp 声明指示。

然而，每个服务器都可能经历时钟漂移，这可能导致令牌在一个服务器上看起来已过期，但在另一个服务器上则未过期。随着分布式系统中协作服务器数量的增加，这可能会导致一些实现上的困难。

资源服务器使用 JwtTimestampValidator 来验证令牌的有效期窗口，并且可以使用 clockSkew 进行配置以缓解上述问题

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
     NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
             JwtDecoders.fromIssuerLocation(issuerUri);

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

     jwtDecoder.setJwtValidator(withClockSkew);

     return jwtDecoder;
}

@Bean
fun jwtDecoder(): JwtDecoder {
    val jwtDecoder: NimbusJwtDecoder = JwtDecoders.fromIssuerLocation(issuerUri) as NimbusJwtDecoder

    val withClockSkew: OAuth2TokenValidator<Jwt> = DelegatingOAuth2TokenValidator(
            JwtTimestampValidator(Duration.ofSeconds(60)),
            JwtIssuerValidator(issuerUri))

    jwtDecoder.setJwtValidator(withClockSkew)

    return jwtDecoder
}

默认情况下，资源服务器配置了 60 秒的时钟偏差。

配置自定义 Validator

使用 OAuth2TokenValidator API 添加对 aud 声明的检查非常简单

Java
Kotlin

OAuth2TokenValidator<Jwt> audienceValidator() {
    return new JwtClaimValidator<List<String>>(AUD, aud -> aud.contains("messaging"));
}

fun audienceValidator(): OAuth2TokenValidator<Jwt?> {
    return JwtClaimValidator<List<String>>(AUD) { aud -> aud.contains("messaging") }
}

或者，为了获得更多控制权，您可以实现自己的 OAuth2TokenValidator

Java
Kotlin

static class AudienceValidator implements OAuth2TokenValidator<Jwt> {
    OAuth2Error error = new OAuth2Error("custom_code", "Custom error message", null);

    @Override
    public OAuth2TokenValidatorResult validate(Jwt jwt) {
        if (jwt.getAudience().contains("messaging")) {
            return OAuth2TokenValidatorResult.success();
        } else {
            return OAuth2TokenValidatorResult.failure(error);
        }
    }
}

// ...

OAuth2TokenValidator<Jwt> audienceValidator() {
    return new AudienceValidator();
}

internal class AudienceValidator : OAuth2TokenValidator<Jwt> {
    var error: OAuth2Error = OAuth2Error("custom_code", "Custom error message", null)

    override fun validate(jwt: Jwt): OAuth2TokenValidatorResult {
        return if (jwt.audience.contains("messaging")) {
            OAuth2TokenValidatorResult.success()
        } else {
            OAuth2TokenValidatorResult.failure(error)
        }
    }
}

// ...

fun audienceValidator(): OAuth2TokenValidator<Jwt> {
    return AudienceValidator()
}

然后，要将其添加到资源服务器中，只需指定 JwtDecoder 实例即可

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
    NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder)
        JwtDecoders.fromIssuerLocation(issuerUri);

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

    jwtDecoder.setJwtValidator(withAudience);

    return jwtDecoder;
}

@Bean
fun jwtDecoder(): JwtDecoder {
    val jwtDecoder: NimbusJwtDecoder = JwtDecoders.fromIssuerLocation(issuerUri) as NimbusJwtDecoder

    val audienceValidator = audienceValidator()
    val withIssuer: OAuth2TokenValidator<Jwt> = JwtValidators.createDefaultWithIssuer(issuerUri)
    val withAudience: OAuth2TokenValidator<Jwt> = DelegatingOAuth2TokenValidator(withIssuer, audienceValidator)

    jwtDecoder.setJwtValidator(withAudience)

    return jwtDecoder
}

如前所述，您也可以在 Boot 中配置 aud 验证。

配置声明集映射

Spring Security 使用 Nimbus 库解析 JWT 并验证其签名。因此，Spring Security 受 Nimbus 对每个字段值的解释以及如何将每个字段强制转换为 Java 类型的影响。

例如，由于 Nimbus 保持 Java 7 兼容，它不使用 Instant 来表示时间戳字段。

并且完全有可能使用不同的库进行 JWT 处理，这可能会做出需要调整的强制转换决策。

或者，简单地说，资源服务器可能出于领域特定的原因想要从 JWT 中添加或删除声明。

为此，资源服务器支持使用 MappedJwtClaimSetConverter 映射 JWT 声明集。

自定义单个声明的转换

默认情况下，MappedJwtClaimSetConverter 将尝试将声明强制转换为以下类型：

声明

Java 类型

aud

Collection<String>

exp

Instant

iat

Instant

iss

String

jti

String

nbf

Instant

sub

String

可以使用 MappedJwtClaimSetConverter.withDefaults 配置单个声明的转换策略

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
    NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build();

    MappedJwtClaimSetConverter converter = MappedJwtClaimSetConverter
            .withDefaults(Collections.singletonMap("sub", this::lookupUserIdBySub));
    jwtDecoder.setClaimSetConverter(converter);

    return jwtDecoder;
}

@Bean
fun jwtDecoder(): JwtDecoder {
    val jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build()

    val converter = MappedJwtClaimSetConverter
            .withDefaults(mapOf("sub" to this::lookupUserIdBySub))
    jwtDecoder.setClaimSetConverter(converter)

    return jwtDecoder
}

这将保留所有默认设置，但会覆盖 sub 的默认声明转换器。

添加声明

MappedJwtClaimSetConverter 也可以用于添加自定义声明，例如，以适应现有系统

Java
Kotlin

MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("custom", custom -> "value"));

MappedJwtClaimSetConverter.withDefaults(mapOf("custom" to Converter<Any, String> { "value" }))

移除声明

使用相同的 API 移除声明也很简单

Java
Kotlin

MappedJwtClaimSetConverter.withDefaults(Collections.singletonMap("legacyclaim", legacy -> null));

MappedJwtClaimSetConverter.withDefaults(mapOf("legacyclaim" to Converter<Any, Any> { null }))

重命名声明

在更复杂的场景中，例如一次咨询多个声明或重命名声明，资源服务器接受任何实现 Converter<Map<String, Object>, Map<String,Object>> 的类

Java
Kotlin

public class UsernameSubClaimAdapter implements Converter<Map<String, Object>, Map<String, Object>> {
    private final MappedJwtClaimSetConverter delegate =
            MappedJwtClaimSetConverter.withDefaults(Collections.emptyMap());

    public Map<String, Object> convert(Map<String, Object> claims) {
        Map<String, Object> convertedClaims = this.delegate.convert(claims);

        String username = (String) convertedClaims.get("user_name");
        convertedClaims.put("sub", username);

        return convertedClaims;
    }
}

class UsernameSubClaimAdapter : Converter<Map<String, Any?>, Map<String, Any?>> {
    private val delegate = MappedJwtClaimSetConverter.withDefaults(Collections.emptyMap())
    override fun convert(claims: Map<String, Any?>): Map<String, Any?> {
        val convertedClaims = delegate.convert(claims)
        val username = convertedClaims["user_name"] as String
        convertedClaims["sub"] = username
        return convertedClaims
    }
}

然后，像通常一样提供该实例即可

Java
Kotlin

@Bean
JwtDecoder jwtDecoder() {
    NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build();
    jwtDecoder.setClaimSetConverter(new UsernameSubClaimAdapter());
    return jwtDecoder;
}

@Bean
fun jwtDecoder(): JwtDecoder {
    val jwtDecoder: NimbusJwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).build()
    jwtDecoder.setClaimSetConverter(UsernameSubClaimAdapter())
    return jwtDecoder
}

配置超时

默认情况下，资源服务器与授权服务器协调时，连接和套接字超时都设置为 30 秒。

在某些场景下，这可能太短了。此外，它没有考虑到更复杂的模式，如指数退避和发现。

要调整资源服务器连接授权服务器的方式，NimbusJwtDecoder 接受一个 RestOperations 实例

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder(RestTemplateBuilder builder) {
    RestOperations rest = builder
            .setConnectTimeout(Duration.ofSeconds(60))
            .setReadTimeout(Duration.ofSeconds(60))
            .build();

    NimbusJwtDecoder jwtDecoder = NimbusJwtDecoder.withIssuerLocation(issuer).restOperations(rest).build();
    return jwtDecoder;
}

@Bean
fun jwtDecoder(builder: RestTemplateBuilder): JwtDecoder {
    val rest: RestOperations = builder
            .setConnectTimeout(Duration.ofSeconds(60))
            .setReadTimeout(Duration.ofSeconds(60))
            .build()
    return NimbusJwtDecoder.withIssuerLocation(issuer).restOperations(rest).build()
}

此外，默认情况下，资源服务器在内存中缓存授权服务器的 JWK set 5 分钟，您可能需要调整此设置。此外，它没有考虑到更复杂的缓存模式，如逐出或使用共享缓存。

要调整资源服务器缓存 JWK set 的方式，NimbusJwtDecoder 接受一个 Cache 实例

Java
Kotlin

@Bean
public JwtDecoder jwtDecoder(CacheManager cacheManager) {
    return NimbusJwtDecoder.withIssuerLocation(issuer)
            .cache(cacheManager.getCache("jwks"))
            .build();
}

@Bean
fun jwtDecoder(cacheManager: CacheManager): JwtDecoder {
    return NimbusJwtDecoder.withIssuerLocation(issuer)
            .cache(cacheManager.getCache("jwks"))
            .build()
}

当给定一个 Cache 时，资源服务器将使用 JWK Set Uri 作为键，JWK Set JSON 作为值。

Spring 本身不是缓存提供者，因此您需要确保包含适当的依赖项，例如 spring-boot-starter-cache 和您喜欢的缓存提供者。

无论是套接字还是缓存超时，您可能更愿意直接使用 Nimbus。为此，请记住 NimbusJwtDecoder 带有一个接受 Nimbus 的 JWTProcessor 的构造函数。

OAuth 2.0 资源服务器 JWT

JWT 的最少依赖

JWT 的最少配置

指定授权服务器

启动期望

运行时期望

JWT 认证如何工作

直接指定授权服务器 JWK Set Uri

提供 Audience

覆盖或替换 Boot 自动配置

使用 jwkSetUri()

使用 decoder()

暴露 JwtDecoder @Bean

配置可信算法

通过 Spring Boot

使用构建器

从 JWK Set 响应

信任单个非对称密钥

通过 Spring Boot

使用构建器

信任单个对称密钥

配置授权

手动提取权限

配置验证

自定义时间戳验证

配置自定义 Validator

配置声明集映射

自定义单个声明的转换

添加声明

移除声明

重命名声明

配置超时

使用 `jwkSetUri()`

使用 `decoder()`

暴露 `JwtDecoder` `@Bean`