最新の安定バージョンについては、Spring Security 6.3.1 を使用してください! |
OAuth 2.0 リソースサーバー JWT
JWT の最小依存関係
ほとんどのリソースサーバーサポートは spring-security-oauth2-resource-server
に収集されます。ただし、JWT のデコードと検証のサポートは spring-security-oauth2-jose
にあります。つまり、JWT でエンコードされたベアラートークンをサポートする作業リソースサーバーを使用するには両方が必要です。
JWT の最小構成
Spring Boot を使用する場合、アプリケーションをリソースサーバーとして構成するには、2 つの基本的な手順が必要です。最初に、必要な依存関係を含め、2 番目に認可サーバーの場所を示します。
認可サーバーの指定
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 (英語) のいずれかが認可サーバーでサポートされているエンドポイントであることも真である必要があります。このエンドポイントは、プロバイダー構成 (英語) エンドポイントまたは認可サーバーのメタデータ [IETF] (英語) エンドポイントと呼ばれます。 |
以上です!
スタートアップの期待
このプロパティとこれらの依存関係を使用すると、リソースサーバーは自動的に JWT エンコードされたベアラートークンを検証するように自身を構成します。
これは、決定論的な起動プロセスを通じてこれを実現します。
プロバイダー構成または認可サーバーメタデータエンドポイントをヒットし、
jwks_url
プロパティのレスポンスを処理します有効な公開鍵について
jwks_url
を照会するための検証戦略を構成しますidp.example.com (英語)
に対して各 JWTiss
クレームを検証する検証戦略を構成します。
このプロセスの結果、リソースサーバーが正常に起動するには、認可サーバーが起動してリクエストを受信する必要があります。
リソースサーバーがクエリを実行したときに認可サーバーがダウンした場合(適切なタイムアウトが与えられた場合)、起動は失敗します。 |
ランタイムの期待
アプリケーションが起動すると、リソースサーバーは Authorization: Bearer
ヘッダーを含むリクエストの処理を試みます。
GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this
このスキームが示されている限り、リソースサーバーはベアラートークン仕様に従ってリクエストの処理を試みます。
整形式の JWT が与えられると、リソースサーバーは次のことを行います。
起動時に
jwks_url
エンドポイントから取得し、JWT ヘッダーと照合した公開鍵に対して署名を検証しますJWT
exp
およびnbf
タイムスタンプと JWTiss
クレームを検証します各スコープを接頭辞
SCOPE_
を持つオーソリティにマップします。
認可サーバーが新しいキーを使用可能にすると、Spring Security は JWT トークンの検証に使用されるキーを自動的に回転させます。 |
デフォルトでは、結果の Authentication#getPrincipal
は Spring Security Jwt
オブジェクトであり、Authentication#getName
は JWT の sub
プロパティ(存在する場合)にマップします。
ここから、次へのジャンプを検討してください。
認可サーバー JWK セット 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 で直接指定することもできます。 |
Boot 自動構成のオーバーライドまたは置換
Spring Boot がリソースサーバーに代わって生成する 2 つの @Bean
があります。
1 つ目は、アプリをリソースサーバーとして構成する SecurityWebFilterChain
です。spring-security-oauth2-jose
を含めると、この SecurityWebFilterChain
は次のようになります。
Java
Kotlin
@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 { }
}
}
}
アプリケーションが SecurityWebFilterChain
Bean を公開しない場合、Spring Boot は上記のデフォルトを公開します。
これを置き換えることは、アプリケーション内で Bean を公開するのと同じくらい簡単です。
Java
Kotlin
@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 { }
}
}
}
上記では、/messages/
で始まる URL の message:read
のスコープが必要です。
oauth2ResourceServer
DSL のメソッドも自動構成をオーバーライドまたは置き換えます。
例: Spring Boot が 2 番目に作成する @Bean
は、String
トークンを Jwt
の検証済みインスタンスにデコードする ReactiveJwtDecoder
です。
Java
Kotlin
@Bean
public ReactiveJwtDecoder jwtDecoder() {
return ReactiveJwtDecoders.fromIssuerLocation(issuerUri);
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
return ReactiveJwtDecoders.fromIssuerLocation(issuerUri)
}
ReactiveJwtDecoders#fromIssuerLocation (Javadoc) を呼び出すと、JWK セット Uri を取得するためにプロバイダー構成または認可サーバーメタデータエンドポイントが呼び出されます。アプリケーションが ReactiveJwtDecoder Bean を公開しない場合、Spring Boot は上記のデフォルトを公開します。 |
そして、その構成は jwkSetUri()
を使用してオーバーライドするか、decoder()
を使用して置き換えることができます。
jwkSetUri()
を使用する
認可サーバーの JWK Set Uri は、構成プロパティとして構成することも、DSL で提供することもできます。
Java
Kotlin
@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()
の使用は、構成プロパティよりも優先されます。
decoder()
を使用する
jwkSetUri()
よりも強力なのは decoder()
です。これは、JwtDecoder
の Boot 自動構成を完全に置き換えます。
Java
Kotlin
@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()
}
}
}
}
これは、検証などのより詳細な構成が必要な場合に便利です。
ReactiveJwtDecoder
の公開 @Bean
または、ReactiveJwtDecoder
を公開すると @Bean
は decoder()
と同じ効果があります。
Java
Kotlin
@Bean
public ReactiveJwtDecoder jwtDecoder() {
return NimbusReactiveJwtDecoder.withJwkSetUri(jwkSetUri).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
return ReactiveJwtDecoders.fromIssuerLocation(issuerUri)
}
信頼できるアルゴリズムの構成
デフォルトでは、NimbusReactiveJwtDecoder
、リソースサーバーは、RS256
を使用したトークンのみを信頼および検証します。
これは、Spring Boot または NimbusJwtDecoder ビルダーを介してカスタマイズできます。
Spring Boot 経由
アルゴリズムを設定する最も簡単な方法は、プロパティとしてです:
spring:
security:
oauth2:
resourceserver:
jwt:
jws-algorithm: RS512
jwk-set-uri: https://idp.example.org/.well-known/jwks.json
ビルダーを使用する
ただし、より強力にするには、NimbusReactiveJwtDecoder
に同梱されているビルダーを使用できます。
Java
Kotlin
@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
は次のように複数のアルゴリズムを信頼するように構成されます。
Java
Kotlin
@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
を呼び出すことができます。
Java
Kotlin
@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 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: ConfigurableListableBeanFactory ->
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
を直接接続するには、次のように適切な NimbusReactiveJwtDecoder
ビルダーを使用するだけです。
Java
Kotlin
@Bean
public ReactiveJwtDecoder jwtDecoder() {
return NimbusReactiveJwtDecoder.withPublicKey(this.key).build();
}
@Bean
fun jwtDecoder(): ReactiveJwtDecoder {
return NimbusReactiveJwtDecoder.withPublicKey(key).build()
}
単一の対称キーを信頼する
単一の対称キーの使用も簡単です。次のように、SecretKey
をロードして適切な NimbusReactiveJwtDecoder
ビルダーを使用するだけです。
Java
Kotlin
@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
属性のいずれかを持ち、付与されたスコープ(または権限)を示します。例:
{ …, "scope" : "messages contacts"}
この場合、リソースサーバーはこれらのスコープを付与された権限のリストに強制し、各スコープの前に文字列 "SCOPE_" を付けようとします。
つまり、エンドポイントまたはメソッドを JWT から派生したスコープで保護するには、対応する式に次のプレフィックスを含める必要があります。
Java
Kotlin
@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 { }
}
}
}
または、同様にメソッドセキュリティで:
Java
Kotlin
@PreAuthorize("hasAuthority('SCOPE_messages')")
public Flux<Message> getMessages(...) {}
@PreAuthorize("hasAuthority('SCOPE_messages')")
fun getMessages(): Flux<Message> { }
権限の手動抽出
ただし、このデフォルトでは不十分な状況がいくつかあります。例: 一部の認可サーバーは scope
属性を使用せず、独自のカスタム属性を持っています。または、リソースサーバーは、属性または属性の構成を内部化されたオーソリティに適合させる必要がある場合もあります。
このために、DSL は jwtAuthenticationConverter()
を公開します:
Java
Kotlin
@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)
}
Jwt
を Authentication
に変換する責任があります。その構成の一部として、Jwt
から付与された権限の Collection
に移行する補助コンバーターを提供できます。
その最終的なコンバーターは、以下の GrantedAuthoritiesExtractor
のようなものです。
Java
Kotlin
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>>
を実装するクラスに完全に置き換えることをサポートしています。
Java
Kotlin
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)
}
}
検証の構成
認可サーバーの発行者 URI を示す最小限の Spring Boot 構成を使用して、リソースサーバーは、iss
クレームと exp
および nbf
タイムスタンプクレームをデフォルトで検証します。
検証をカスタマイズする必要がある状況では、リソースサーバーには 2 つの標準バリデーターが付属しており、カスタム OAuth2TokenValidator
インスタンスも受け入れます。
タイムスタンプ検証のカスタマイズ
通常、JWT には有効期間があり、ウィンドウの開始は nbf
クレームで示され、終了は exp
クレームで示されます。
ただし、すべてのサーバーでクロックドリフトが発生する可能性があります。これにより、あるサーバーではトークンが期限切れになり、別のサーバーでは期限切れになります。これにより、分散システムでコラボレーションサーバーの数が増えると、実装の胸焼けが発生する可能性があります。
リソースサーバーは JwtTimestampValidator
を使用してトークンの有効期間を検証し、clockSkew
で構成して上記の問題を軽減できます。
Java
Kotlin
@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
}
デフォルトでは、ResourceServer は 60 秒のクロックスキューを構成します。 |
カスタム検証ツールの構成
aud
クレームのチェックの追加は、OAuth2TokenValidator
API を使用すると簡単です。
Java
Kotlin
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
インスタンスを指定するだけです。
Java
Kotlin
@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
}