
# spring_boot_starter_flutter_security

`spring_boot_starter_flutter_security` は、OAuth 2.0 と OpenID Connect (Keycloak、Google、Apple、Okta、Auth0 など) で Flutter アプリのユーザーをログインさせ、秘密情報をデバイスに保持します。そのためにアプリが必要とするプラットフォームのコードを持ち込みます。各プラットフォームの安全なストレージ (キーチェーン、Android Keystore、DPAPI、Secret Service)、システムのログインウィンドウ、DPoP のための鍵です。その上に、アプリ独自の秘密情報のためのテンプレート、ログイン中のユーザーに従うウィジェット、既製のログイン画面、ナビゲーションのスターターの画面のためのガードがあります。

## 使う理由

ユーザーをログインさせるアプリには、トークンのための安全な場所、システムのログインウィンドウ (アプリがパスワードを見ることはなく、シングルサインオンが動くように)、PKCE、すべての応答のチェック、起動時の更新、取り消しを伴うログアウトが必要です。ブラウザーではまったく別のものが必要です。トークンがページに届いてはなりません。手で書けば、何週間ものプラットフォームのコードとセキュリティのレビューになります。ここでは、Spring の OAuth2 クライアントの登録の上で、スマートフォンでも、デスクトップでも、ブラウザーでも同じ、`login`、`restore`、`logout` の三つの呼び出しを持つ一つのサービスです。

これは Flutter のスターターではなく独自のパッケージにあります。プラットフォームのコード (Swift、Kotlin、二つの Android のアクティビティ) は、ログインするアプリだけが抱えるべきだからです。Spring Boot と同じく、アプリは必要なときにセキュリティを追加します。

## セットアップ

```yaml
# pubspec.yaml
dependencies:
  flutter:
    sdk: flutter
  spring_boot_starter_flutter_security: ^0.9.0

dev_dependencies:
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

一つのパッケージ、一つのインポートです。[spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)、[spring_boot_starter_flutter_navigation](../spring-boot-starter-flutter-navigation/index.md)、OAuth2 クライアント (`spring_boot_starter_oauth2_client`: 登録と認可済みのクライアント)、[spring_security_core](../spring-security-core/index.md) (`SecurityContextHolder`、`@PreAuthorize`) に依存し、それらを再エクスポートします。Flutter のスターターの代わりにこのパッケージを列挙してください。

```dart
import 'package:spring_boot_starter_flutter_security/spring_boot_starter_flutter_security.dart';
```

Feign クライアントを持つアプリは、`spring_boot_starter_feign` を自分で列挙してインポートします。

スターターには Flutter 3.50 以降 (Dart 3.14) が必要です。その Android の部分は、Flutter 3.50 のテンプレートのバージョンである Android Gradle Plugin 9.3.1 でビルドされ、その Kotlin はプラグインに組み込まれた Kotlin のサポートでコンパイルされます。Flutter 3.50 のアプリは、いずれにせよ AGP 9.1.1 以降を必要とし (Flutter はそれより古いものを拒みます)、Flutter は Gradle 9.5.0 を推奨しています。

ログイン画面はデザインライブラリーをインポートしません。`material` や `cupertino` の種類のアプリでは、そのデザインのスターターの見た目になります ([ログイン画面](login-screens.md#そのデザインはアプリに従う) を参照)。

## 例

```dart
// アプリのアカウント: 誰がログインしているかと、三つの呼び出し。
@Service()
class Account {
  Account(this._login);

  final OAuth2LoginService _login;

  Future<void> start() => _login.restore();          // 前回からログイン中か?
  Future<void> signIn() => _login.login('keycloak'); // システムのログインウィンドウ
  Future<void> signOut() => _login.logout();         // 取り消して忘れる
}

// ログインとログアウトのたびに再ビルドされる。
class Header extends StatelessWidget {
  const Header({super.key});

  @override
  Widget build(BuildContext context) =>
      Text('Hello, ${context.principal?.name ?? 'guest'}');
}
```

```yaml
# lib/resources/application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: neon-app                 # パブリッククライアント: シークレットなし
            scope: openid,profile,email
            redirect-uri: dev.neon.books:/oauth2/callback
        provider:
          keycloak:
            issuer-uri: https://id.neon.books/realms/neon
```

```yaml
# lib/resources/application-web.yml: ブラウザーではアプリのサーバーがログインする
spring:
  flutter:
    security:
      web:
        server-url: https://api.neon.books
        user-endpoint: /api/me
```

## 実行する

- iOS と macOS では、`login('keycloak')` はプロバイダーのページを Safari のシートで開きます。Android では Chrome Custom Tab で開きます (リダイレクトのアクティビティを宣言してください。[トークンとログインウィンドウ](tokens-and-login-window.md) を参照)。Windows と Linux ではデフォルトのブラウザーで開き、リダイレクトは `127.0.0.1` で受け取ります。
- トークンはプラットフォームの安全なストレージに入ります。次の起動時に、`restore()` がユーザーを呼び戻し、トークンを更新します。
- ブラウザーでは、`login` はページをサーバーのログイン ([spring_boot_starter_security](../spring-boot-starter-security/index.md) の `oauth2Login()`) に送ります。ページが保持するのは `HttpOnly` のセッション Cookie だけです。

## 内容

- [アプリのログイン](app-login.md): スマートフォンとデスクトップでの `OAuth2LoginService`。`login`、`restore`、`logout`、チェック、Bean。
- [Web: サーバーがログインする](web-server-mode.md): Backend for Frontend のログイン、ユーザーのエンドポイント、Cookie と CSRF。
- [サーバーなしの Web: spa モード](web-spa-mode.md): ブラウザーがログインし、トークンはタブのメモリーに、サイレントログイン、Content Security Policy。
- [トークンとログインウィンドウ](tokens-and-login-window.md): `SecretStore`、`AuthorizationWindow`、各プラットフォームのセットアップ、`https` のリダイレクト。
- [プロバイダー: Google と Apple](providers.md): 各プロバイダーが必要とするもの、Sign in with Apple のシート。
- [DPoP](dpop.md): Secure Enclave や Keystore の鍵に結び付けられたトークン。
- [SecretTemplate](secrets.md): オブジェクトとしてのアプリ独自の秘密情報。
- [ユーザーに従うウィジェット](principal-widgets.md): `context.principal`、`PrincipalBuilder`、`PrincipalView`。
- [ログイン画面](login-screens.md): `LoginForm`、`OAuth2LoginButton`、Google、Apple、Microsoft、GitHub のボタン。
- [ガードされた画面](guarded-screens.md): ナビゲーションの画面に付ける `@PreAuthorize`。
- [テスト](testing.md): ユーザーとして実行するコード、ログインのフェイク。
- [すべてのプロパティ](properties.md): スターターが読むすべてのキーと、OAuth2 クライアントのもの。
- [Spring との違い](differences.md)

## Spring (Java) との対応

Spring Security は、サーバー上でブラウザーをログインさせます (`oauth2Login()`、セッションにトークンを持つコンフィデンシャルクライアント)。Java にはアプリがないので、アプリの側に対応するものはありません。チェックは Spring の `OAuth2LoginAuthenticationFilter`、`OidcAuthorizationCodeAuthenticationProvider`、`OidcUserService` のものであり、ブラウザーでのサーバーモードは `oauth2Login()` そのものです。

## 関連項目

- [spring_boot_starter_flutter](../spring-boot-starter-flutter/index.md)
- [spring_boot_starter_security](../spring-boot-starter-security/index.md)
- [spring_security_core](../spring-security-core/index.md)
- [ビルドに含まれるもの](optimizations.md)
