最新の安定バージョンについては、Spring Security 6.3.1 を使用してください！

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 つのステップで構成されます。

  1. 必要な依存関係を含めます。

  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 トークンの場合、リソースサーバーは次のようになります。

  1. 提供されたクレデンシャルとトークンを使用して、提供されたイントロスペクションエンドポイントを照会します。

  2. { 'active' : true } 属性のレスポンスをインスペクションします。

  3. 各スコープを、プレフィックスが 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 を公開することにより、これを置き換えることができます。

SecurityWebFilterChain の交換

  • 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()
            }
        }
    }
}

これは、権限マッピングや JWT の取り消しなどのより深い構成が必要な場合に便利です。

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()
}