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、鍵、シークレットをログに出しません。
内容
- 登録: クライアントとプロバイダー、共通のプロバイダー、検出、リダイレクト URI、Apple。
- 認可済みクライアント: マネージャー、リフレッシュ、クライアントクレデンシャル、どこでも使えるトークン。
- Feign の呼び出しのトークン:
spring.feign.oauth2.*、インターセプターとエラーデコーダー。 - OpenID Connect: ユーザー、ID トークンとそのチェック。
- DPoP: クライアントの鍵にバインドされたトークン。
- すべてのプロパティ: スターターのすべてのキー。
- Spring との違い: Spring Security と動作が異なる点。
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 との違い にあります。