spring_boot_starter_oauth2_client

spring_boot_starter_oauth2_client は Spring for Dart の OAuth 2.0 と OpenID Connect のクライアントです。Spring Security の OAuth2 クライアントに Spring Boot の自動構成を組み合わせたものです。サービスは自身の (クライアントクレデンシャルの) トークンで別のサービスを呼びます。サーバーはセキュリティスターターの oauth2Login() を通じて、Keycloak、Google、Auth0、Okta でユーザーをログインさせます。Flutter アプリは spring_boot_starter_flutter_security を通じてユーザーをログインさせます。そのすべてが、このスターターの登録、トークンエンドポイントのクライアント、認可済みクライアントを使います。

使う理由

アクセストークンで API を呼ぶのは、見た目以上にプロトコルの仕事です。プロバイダーのエンドポイント (その発行者から検出)、正しいクライアント認証によるトークンエンドポイント、トークンが期限切れになる前のリフレッシュ (十の呼び出しが同時に求めても一回)、API に拒否された後のトークンの更新、そしてログインでは PKCE、state、nonce、ID トークンのチェックがあります。このスターターは Spring Boot の spring.security.oauth2.client.* プロパティからそのすべてを行い、アプリケーションの Feign クライアントはそのまま動きます。純粋な Dart で、spring_boot_dart が動く場所ならどこでも動きます。VM、Flutter、Web です。

セットアップ

# pubspec.yaml
dependencies:
  spring_boot_starter_oauth2_client: ^0.9.0
  spring_boot_starter_feign: ^0.9.0     # トークンを運ぶ Feign クライアントにだけ必要

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0

インポートは一つです: package:spring_boot_starter_oauth2_client/spring_boot_starter_oauth2_client.dart は spring_security_core と spring_web_dart (そしてそれらを通じて spring_boot_dart とロギング) を再エクスポートします。Feign スターターは再エクスポートしません。クライアントを宣言する場所でインポートしてください。

ユーザーをログインさせるサーバーは、代わりに spring_boot_starter_security を加えます。これはこのパッケージに依存して再エクスポートし、oauth2Login() を追加します。

例

サービスが自身のトークンでパートナーの API を呼びます。

# lib/resources/application.properties
spring.security.oauth2.client.registration.partner.client-id=shop
spring.security.oauth2.client.registration.partner.client-secret=${PARTNER_SECRET}
spring.security.oauth2.client.registration.partner.authorization-grant-type=client_credentials
spring.security.oauth2.client.registration.partner.scope=orders.read
spring.security.oauth2.client.provider.partner.token-uri=https://id.partner.example/oauth2/token

# すべての Feign の呼び出しがトークンを運ぶ。
spring.feign.oauth2.enabled=true
spring.feign.oauth2.client-registration-id=partner
import 'package:spring_boot_starter_feign/spring_boot_starter_feign.dart';
import 'package:spring_boot_starter_oauth2_client/spring_boot_starter_oauth2_client.dart';

@FeignClient('orders', url: r'${partner.url}')
abstract interface class OrdersClient {
  @GetMapping('/orders')
  Future<List<Order>> orders(); // Authorization: Bearer <token>。期限切れの前にリフレッシュされる
}

どこでどのフローを使うか

クライアント フロー パッケージ
サーバーからサーバー クライアントクレデンシャル、OAuth2AuthorizedClientManager このパッケージ
サーバーのページ、Flutter Web oauth2Login(): サーバーはコンフィデンシャルクライアントで、トークンはそのセッションにとどまる。ブラウザーが持つのは HttpOnly のセッション Cookie だけ spring_boot_starter_security
Flutter の iOS、Android、macOS、Windows、Linux アプリのログイン: PKCE を使う認可コード、パブリッククライアント (RFC 8252)、システムのログインウィンドウ、セキュアストレージのトークン spring_boot_starter_flutter_security

起動するもの

アプリケーションがその型の Bean を宣言すると、各 Bean は引き下がります。

Bean の型 デフォルト
ClientRegistrationRepository registration.* プロパティのメモリ上のリポジトリ。
OAuth2AuthorizedClientService InMemoryOAuth2AuthorizedClientService: トークンはプログラムが止まると忘れられる。
OAuth2AuthorizedClientManager 認可コード、リフレッシュトークン、クライアントクレデンシャルを持つ AuthorizedClientServiceOAuth2AuthorizedClientManager。
OAuth2AccessTokenResponseClient<...> (三つ) HttpTransport の上の DefaultAuthorizationCodeTokenResponseClient、DefaultRefreshTokenTokenResponseClient、DefaultClientCredentialsTokenResponseClient。
OidcIdTokenDecoder TokenEndpointOidcIdTokenDecoder (セキュリティスターターが署名をチェックするものに置き換える)。
OAuth2UserService<...> (二つ) DefaultOAuth2UserService、OidcUserService。
OAuth2AccessTokenInterceptor、ErrorDecoder spring.feign.oauth2.enabled=true の場合。
DPoPKey 実行ごとにメモリ上で作られる SoftwareDPoPKey。
clientSecretResolver client-secret-jwt.* のための JwtClientSecretResolver。

別の自動構成は、そのモジュールが先に登録されると (@AutoConfigurationModule(before: ['springBootStarterOauth2ClientAutoConfiguration']))、@ConditionalOnMissingBean で守られたその Bean によって、同じ方法でこれらを置き換えます。セキュリティスターターは OidcIdTokenDecoder について、Flutter のセキュリティパッケージは OAuth2AuthorizedClientService と DPoPKey についてそうします。

スターターの中の何物も、トークン、コード、verifier、鍵、シークレットをログに出しません。

内容

Spring (Java) との対応

spring:
  security:
    oauth2:
      client:
        registration:
          partner:
            client-id: shop
            authorization-grant-type: client_credentials

プロパティは Spring Boot のものです。Spring では、spring-boot-starter-oauth2-client は Web セキュリティと oauth2Login() も取り込みます。ここではこのパッケージはクライアントだけです。Flutter アプリやブラウザーでも動かなければならないためです。検出は起動時ではなく最初の使用時に行われます。すべての違いは Spring との違い にあります。

関連項目