OAuth 2.0 リソースサーバー Opaque トークン
イントロスペクションの最小限の依存関係
JWT の最小依存関係に従って、ほとんどの ResourceServer サポートは spring-security-oauth2-resource-server
に収集されます。ただし、カスタム ReactiveOpaqueTokenIntrospector
を提供しない限り、リソースサーバーは ReactiveOpaqueTokenIntrospector
にフォールバックします。これは、不透明なベアラートークンをサポートする最小限のリソースサーバーを機能させるには、spring-security-oauth2-resource-server
と oauth2-oidc-sdk
の両方が必要であることを意味します。oauth2-oidc-sdk
の正しいバージョンを判別するには、spring-security-oauth2-resource-server
を参照してください。
イントロスペクションの最小構成
通常、認証サーバーによってホストされている OAuth 2.0 イントロスペクションエンドポイント [IETF] (英語) を使用して Opaque トークンを検証できます。これは、失効が必要な場合に便利です。
Spring Boot を使用する場合、イントロスペクションを使用するリソースサーバーとしてアプリケーションを構成することは、次の 2 つのステップで構成されます。
必要な依存関係を含めます。
イントロスペクションエンドポイントの詳細を示します。
認可サーバーの指定
イントロスペクションエンドポイントの場所を指定できます。
spring:
security:
oauth2:
resourceserver:
opaque-token:
introspection-uri: https://idp.example.com/introspect
client-id: client
client-secret: secret
ここで、idp.example.com/introspect (英語)
は認証サーバーによってホストされるイントロスペクションエンドポイントであり、client-id
および client-secret
はそのエンドポイントをヒットするために必要な資格情報です。
リソースサーバーは、これらのプロパティを使用して、受信 JWT をさらに自己構成し、その後検証します。
認可サーバーがトークンが有効であるとレスポンスした場合、有効です。 |
スタートアップの期待
このプロパティとこれらの依存関係を使用すると、ResourceServer は不透明ベアラートークンを検証するように自動的に構成します。
この起動プロセスは、エンドポイントを検出する必要がなく、追加の検証ルールが追加されないため、JWT よりもかなり簡単です。
ランタイムの期待
アプリケーションが開始されると、ResourceServer は Authorization: Bearer
ヘッダーを含むすべてのリクエストを処理しようとします。
GET / HTTP/1.1
Authorization: Bearer some-token-value # Resource Server will process this
このスキームが示されている限り、ResourceServer は BearerToken 仕様に従ってリクエストを処理しようとします。
Opaque トークンの場合、リソースサーバーは次のようになります。
提供されたクレデンシャルとトークンを使用して、提供されたイントロスペクションエンドポイントを照会します。
{ 'active' : true }
属性のレスポンスをインスペクションします。各スコープを、プレフィックスが
SCOPE_
のオーソリティにマップします。
デフォルトでは、結果の Authentication#getPrincipal
は Spring Security OAuth2AuthenticatedPrincipal (Javadoc)
オブジェクトであり、Authentication#getName
は、トークンの sub
プロパティ(存在する場合)にマップされます。
ここから、次の場所にジャンプできます。
認証後の属性の検索
トークンが認証されると、BearerTokenAuthentication
のインスタンスが SecurityContext
に設定されます。
これは、構成で @EnableWebFlux
を使用する場合、@Controller
メソッドで使用できることを意味します。
Java
Kotlin
@GetMapping("/foo")
public Mono<String> foo(BearerTokenAuthentication authentication) {
return Mono.just(authentication.getTokenAttributes().get("sub") + " is the subject");
}
@GetMapping("/foo")
fun foo(authentication: BearerTokenAuthentication): Mono<String> {
return Mono.just(authentication.tokenAttributes["sub"].toString() + " is the subject")
}
BearerTokenAuthentication
は OAuth2AuthenticatedPrincipal
を保持するため、コントローラーメソッドでも使用できることも意味します。
Java
Kotlin
@GetMapping("/foo")
public Mono<String> foo(@AuthenticationPrincipal OAuth2AuthenticatedPrincipal principal) {
return Mono.just(principal.getAttribute("sub") + " is the subject");
}
@GetMapping("/foo")
fun foo(@AuthenticationPrincipal principal: OAuth2AuthenticatedPrincipal): Mono<String> {
return Mono.just(principal.getAttribute<Any>("sub").toString() + " is the subject")
}
SpEL で属性を検索する
Spring 式言語(SpEL)を使用して属性にアクセスできます。
例: @PreAuthorize
アノテーションを使用できるように @EnableReactiveMethodSecurity
を使用する場合は、次のことができます。
Java
Kotlin
@PreAuthorize("principal?.attributes['sub'] = 'foo'")
public Mono<String> forFoosEyesOnly() {
return Mono.just("foo");
}
@PreAuthorize("principal.attributes['sub'] = 'foo'")
fun forFoosEyesOnly(): Mono<String> {
return Mono.just("foo")
}
Boot 自動構成のオーバーライドまたは置換
Spring Boot は、リソースサーバー用に 2 つの @Bean
インスタンスを生成します。
1 つは、アプリケーションをリソースサーバーとして構成する SecurityWebFilterChain
です。Opaque トークンを使用する場合、この SecurityWebFilterChain
は次のようになります。
Java
Kotlin
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http
.authorizeExchange(exchanges -> exchanges
.anyExchange().authenticated()
)
.oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken)
return http.build();
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
authorizeExchange {
authorize(anyExchange, authenticated)
}
oauth2ResourceServer {
opaqueToken { }
}
}
}
アプリケーションが SecurityWebFilterChain
Bean を公開しない場合、Spring Boot はデフォルトの Bean(前のリストに示されている)を公開します。
アプリケーション内で Bean を公開することにより、これを置き換えることができます。
Java
Kotlin
import static org.springframework.security.oauth2.core.authorization.OAuth2ReactiveAuthorizationManagers.hasScope;
@Configuration
@EnableWebFluxSecurity
public class MyCustomSecurityConfiguration {
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http
.authorizeExchange(exchanges -> exchanges
.pathMatchers("/messages/**").access(hasScope("message:read"))
.anyExchange().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.opaqueToken(opaqueToken -> opaqueToken
.introspector(myIntrospector())
)
);
return http.build();
}
}
import org.springframework.security.oauth2.core.authorization.OAuth2ReactiveAuthorizationManagers.hasScope
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
authorizeExchange {
authorize("/messages/**", hasScope("message:read"))
authorize(anyExchange, authenticated)
}
oauth2ResourceServer {
opaqueToken {
introspector = myIntrospector()
}
}
}
}
上記の例では、/messages/
で始まる URL に対して message:read
のスコープが必要です。
oauth2ResourceServer
DSL のメソッドも、自動構成をオーバーライドまたは置換します。
例: Spring Boot が 2 番目に作成する @Bean
は、String
トークンを OAuth2AuthenticatedPrincipal
の検証済みインスタンスにデコードする ReactiveOpaqueTokenIntrospector
です。
Java
Kotlin
@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return new NimbusReactiveOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
return NimbusReactiveOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret)
}
アプリケーションが ReactiveOpaqueTokenIntrospector
Bean を公開しない場合、Spring Boot はデフォルトのもの(前のリストに示されている)を公開します。
introspectionUri()
および introspectionClientCredentials()
を使用して構成をオーバーライドするか、introspector()
を使用して構成を置き換えることができます。
introspectionUri()
を使用する
認可サーバーのイントロスペクション URI を構成プロパティとして構成するか、DSL で提供することができます。
Java
Kotlin
@Configuration
@EnableWebFluxSecurity
public class DirectlyConfiguredIntrospectionUri {
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http
.authorizeExchange(exchanges -> exchanges
.anyExchange().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.opaqueToken(opaqueToken -> opaqueToken
.introspectionUri("https://idp.example.com/introspect")
.introspectionClientCredentials("client", "secret")
)
);
return http.build();
}
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
authorizeExchange {
authorize(anyExchange, authenticated)
}
oauth2ResourceServer {
opaqueToken {
introspectionUri = "https://idp.example.com/introspect"
introspectionClientCredentials("client", "secret")
}
}
}
}
introspectionUri()
の使用は、構成プロパティよりも優先されます。
introspector()
を使用する
introspector()
は introspectionUri()
よりも強力です。これは、ReactiveOpaqueTokenIntrospector
の Boot 自動構成を完全に置き換えます。
Java
Kotlin
@Configuration
@EnableWebFluxSecurity
public class DirectlyConfiguredIntrospector {
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http
.authorizeExchange(exchanges -> exchanges
.anyExchange().authenticated()
)
.oauth2ResourceServer(oauth2 -> oauth2
.opaqueToken(opaqueToken -> opaqueToken
.introspector(myCustomIntrospector())
)
);
return http.build();
}
}
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
authorizeExchange {
authorize(anyExchange, authenticated)
}
oauth2ResourceServer {
opaqueToken {
introspector = myCustomIntrospector()
}
}
}
}
ReactiveOpaqueTokenIntrospector
の公開 @Bean
または、ReactiveOpaqueTokenIntrospector
を公開すると @Bean
は introspector()
と同じ効果があります。
Java
Kotlin
@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return new NimbusReactiveOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret);
}
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
return NimbusReactiveOpaqueTokenIntrospector(introspectionUri, clientId, clientSecret)
}
認可の構成
OAuth 2.0 イントロスペクションエンドポイントは通常、scope
属性を返します。これは、付与されたスコープ(または権限)を示します。例:
{ ..., "scope" : "messages contacts"}
この場合、リソースサーバーは、これらのスコープを許可された権限のリストに強制的に入れ、各スコープの前に文字列 SCOPE_
を付けます。
これは、Opaque トークンから派生したスコープでエンドポイントまたはメソッドを保護するために、対応する式に次のプレフィックスを含める必要があることを意味します。
Java
Kotlin
import static org.springframework.security.oauth2.core.authorization.OAuth2ReactiveAuthorizationManagers.hasScope;
@Configuration
@EnableWebFluxSecurity
public class MappedAuthorities {
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http
.authorizeExchange(exchange -> exchange
.pathMatchers("/contacts/**").access(hasScope("contacts"))
.pathMatchers("/messages/**").access(hasScope("messages"))
.anyExchange().authenticated()
)
.oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::opaqueToken);
return http.build();
}
}
import org.springframework.security.oauth2.core.authorization.OAuth2ReactiveAuthorizationManagers.hasScope
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
return http {
authorizeExchange {
authorize("/contacts/**", hasScope("contacts"))
authorize("/messages/**", hasScope("messages"))
authorize(anyExchange, authenticated)
}
oauth2ResourceServer {
opaqueToken { }
}
}
}
メソッドセキュリティと同様のことができます。
Java
Kotlin
@PreAuthorize("hasAuthority('SCOPE_messages')")
public Flux<Message> getMessages(...) {}
@PreAuthorize("hasAuthority('SCOPE_messages')")
fun getMessages(): Flux<Message> { }
権限の手動抽出
デフォルトでは、Opaque トークンサポートは、イントロスペクションレスポンスからスコープクレームを抽出し、それを個々の GrantedAuthority
インスタンスに解析します。
次の例を考えてみましょう。
{
"active" : true,
"scope" : "message:read message:write"
}
イントロスペクションのレスポンスが前の例のようである場合、リソースサーバーは、2 つの権限を持つ Authentication
を生成します。1 つは message:read
用で、もう 1 つは message:write
用です。
属性セットを調べて独自の方法で変換するカスタム ReactiveOpaqueTokenIntrospector
を使用して、動作をカスタマイズできます。
Java
Kotlin
public class CustomAuthoritiesOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private ReactiveOpaqueTokenIntrospector delegate =
new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
return this.delegate.introspect(token)
.map(principal -> new DefaultOAuth2AuthenticatedPrincipal(
principal.getName(), principal.getAttributes(), extractAuthorities(principal)));
}
private Collection<GrantedAuthority> extractAuthorities(OAuth2AuthenticatedPrincipal principal) {
List<String> scopes = principal.getAttribute(OAuth2IntrospectionClaimNames.SCOPE);
return scopes.stream()
.map(SimpleGrantedAuthority::new)
.collect(Collectors.toList());
}
}
class CustomAuthoritiesOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
override fun introspect(token: String): Mono<OAuth2AuthenticatedPrincipal> {
return delegate.introspect(token)
.map { principal: OAuth2AuthenticatedPrincipal ->
DefaultOAuth2AuthenticatedPrincipal(
principal.name, principal.attributes, extractAuthorities(principal))
}
}
private fun extractAuthorities(principal: OAuth2AuthenticatedPrincipal): Collection<GrantedAuthority> {
val scopes = principal.getAttribute<List<String>>(OAuth2IntrospectionClaimNames.SCOPE)
return scopes
.map { SimpleGrantedAuthority(it) }
}
}
その後、@Bean
として公開することにより、このカスタムイントロスペクターを構成できます。
Java
Kotlin
@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return new CustomAuthoritiesOpaqueTokenIntrospector();
}
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
return CustomAuthoritiesOpaqueTokenIntrospector()
}
JWT でのイントロスペクションの使用
よくある質問は、イントロスペクションが JWT と互換性があるかどうかです。Spring Security の Opaque トークンサポートは、トークンの形式を気にしないように設計されています。提供されたイントロスペクションエンドポイントにトークンを喜んで渡します。
JWT が取り消された場合に備えて、リクエストごとに認証サーバーに確認する必要があるとします。
トークンに JWT 形式を使用している場合でも、検証方法はイントロスペクションです。つまり、次のことを実行する必要があります。
spring:
security:
oauth2:
resourceserver:
opaque-token:
introspection-uri: https://idp.example.org/introspection
client-id: client
client-secret: secret
この場合、結果の Authentication
は BearerTokenAuthentication
になります。対応する OAuth2AuthenticatedPrincipal
の属性は、イントロスペクションエンドポイントによって返されたものです。
ただし、何らかの理由で、イントロスペクションエンドポイントがトークンがアクティブであるかどうかのみを返すと仮定します。それで?
この場合、エンドポイントにヒットするカスタム ReactiveOpaqueTokenIntrospector
を作成できますが、返されたプリンシパルを更新して、JWT が属性として要求するようにします。
Java
Kotlin
public class JwtOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private ReactiveOpaqueTokenIntrospector delegate =
new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
private ReactiveJwtDecoder jwtDecoder = new NimbusReactiveJwtDecoder(new ParseOnlyJWTProcessor());
public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
return this.delegate.introspect(token)
.flatMap(principal -> this.jwtDecoder.decode(token))
.map(jwt -> new DefaultOAuth2AuthenticatedPrincipal(jwt.getClaims(), NO_AUTHORITIES));
}
private static class ParseOnlyJWTProcessor implements Converter<JWT, Mono<JWTClaimsSet>> {
public Mono<JWTClaimsSet> convert(JWT jwt) {
try {
return Mono.just(jwt.getJWTClaimsSet());
} catch (Exception ex) {
return Mono.error(ex);
}
}
}
}
class JwtOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
private val jwtDecoder: ReactiveJwtDecoder = NimbusReactiveJwtDecoder(ParseOnlyJWTProcessor())
override fun introspect(token: String): Mono<OAuth2AuthenticatedPrincipal> {
return delegate.introspect(token)
.flatMap { jwtDecoder.decode(token) }
.map { jwt: Jwt -> DefaultOAuth2AuthenticatedPrincipal(jwt.claims, NO_AUTHORITIES) }
}
private class ParseOnlyJWTProcessor : Converter<JWT, Mono<JWTClaimsSet>> {
override fun convert(jwt: JWT): Mono<JWTClaimsSet> {
return try {
Mono.just(jwt.jwtClaimsSet)
} catch (e: Exception) {
Mono.error(e)
}
}
}
}
その後、@Bean
として公開することにより、このカスタムイントロスペクターを構成できます。
Java
Kotlin
@Bean
public ReactiveOpaqueTokenIntrospector introspector() {
return new JwtOpaqueTokenIntropsector();
}
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
return JwtOpaqueTokenIntrospector()
}
/userinfo
エンドポイントの呼び出し
一般的に、リソースサーバーは基になるユーザーを気にしませんが、代わりに、付与された権限を気にします。
ただし、認証ステートメントをユーザーに結び付けることが重要な場合があります。
アプリケーションが spring-security-oauth2-client
も使用し、適切な ClientRegistrationRepository
を設定している場合は、カスタム OpaqueTokenIntrospector
を使用してこれを行うことができます。次のリストの実装は、次の 3 つのことを行います。
トークンの有効性を確認するために、イントロスペクションエンドポイントに委譲します。
/userinfo
エンドポイントに関連付けられている適切なクライアント登録を検索します。/userinfo
エンドポイントからレスポンスを呼び出して返します。
Java
Kotlin
public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private final ReactiveOpaqueTokenIntrospector delegate =
new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
private final ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService =
new DefaultReactiveOAuth2UserService();
private final ReactiveClientRegistrationRepository repository;
// ... constructor
@Override
public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
return Mono.zip(this.delegate.introspect(token), this.repository.findByRegistrationId("registration-id"))
.map(t -> {
OAuth2AuthenticatedPrincipal authorized = t.getT1();
ClientRegistration clientRegistration = t.getT2();
Instant issuedAt = authorized.getAttribute(ISSUED_AT);
Instant expiresAt = authorized.getAttribute(OAuth2IntrospectionClaimNames.EXPIRES_AT);
OAuth2AccessToken accessToken = new OAuth2AccessToken(BEARER, token, issuedAt, expiresAt);
return new OAuth2UserRequest(clientRegistration, accessToken);
})
.flatMap(this.oauth2UserService::loadUser);
}
}
class UserInfoOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
private val oauth2UserService: ReactiveOAuth2UserService<OAuth2UserRequest, OAuth2User> = DefaultReactiveOAuth2UserService()
private val repository: ReactiveClientRegistrationRepository? = null
// ... constructor
override fun introspect(token: String?): Mono<OAuth2AuthenticatedPrincipal> {
return Mono.zip<OAuth2AuthenticatedPrincipal, ClientRegistration>(delegate.introspect(token), repository!!.findByRegistrationId("registration-id"))
.map<OAuth2UserRequest> { t: Tuple2<OAuth2AuthenticatedPrincipal, ClientRegistration> ->
val authorized = t.t1
val clientRegistration = t.t2
val issuedAt: Instant? = authorized.getAttribute(ISSUED_AT)
val expiresAt: Instant? = authorized.getAttribute(OAuth2IntrospectionClaimNames.EXPIRES_AT)
val accessToken = OAuth2AccessToken(BEARER, token, issuedAt, expiresAt)
OAuth2UserRequest(clientRegistration, accessToken)
}
.flatMap { userRequest: OAuth2UserRequest -> oauth2UserService.loadUser(userRequest) }
}
}
spring-security-oauth2-client
を使用していない場合でも、非常に簡単です。WebClient
の独自のインスタンスで /userinfo
を呼び出すだけです。
Java
Kotlin
public class UserInfoOpaqueTokenIntrospector implements ReactiveOpaqueTokenIntrospector {
private final ReactiveOpaqueTokenIntrospector delegate =
new NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret");
private final WebClient rest = WebClient.create();
@Override
public Mono<OAuth2AuthenticatedPrincipal> introspect(String token) {
return this.delegate.introspect(token)
.map(this::makeUserInfoRequest);
}
}
class UserInfoOpaqueTokenIntrospector : ReactiveOpaqueTokenIntrospector {
private val delegate: ReactiveOpaqueTokenIntrospector = NimbusReactiveOpaqueTokenIntrospector("https://idp.example.org/introspect", "client", "secret")
private val rest: WebClient = WebClient.create()
override fun introspect(token: String): Mono<OAuth2AuthenticatedPrincipal> {
return delegate.introspect(token)
.map(this::makeUserInfoRequest)
}
}
いずれにしても、ReactiveOpaqueTokenIntrospector
を作成したら、それを @Bean
として公開してデフォルトをオーバーライドする必要があります。
Java
Kotlin
@Bean
ReactiveOpaqueTokenIntrospector introspector() {
return new UserInfoOpaqueTokenIntrospector();
}
@Bean
fun introspector(): ReactiveOpaqueTokenIntrospector {
return UserInfoOpaqueTokenIntrospector()
}